Filtering¶

Most list endpoints in NeMo Platform accept a filter parameter for narrowing results. Filter values can be expressed as dot flags (CLI only), bracket notation (URLs), text syntax (compact, URL-aware callers), or JSON (SDKs and programmatic builders).

Prefer the form that's most natural for the caller:

CLI: --filter.<field> dot flags for simple cases → --filter '<text>' when you need operators/boolean logic → --filter '<json>' for complex nested queries.
REST URL: ?filter[field][$op]=value bracket notation → JSON blob (?filter={...} URL-encoded) → text syntax (readable but requires URL-encoding spaces and quotes).
SDK: JSON dicts on typed endpoints; text or JSON strings on endpoints whose filter parameter is typed as str (client.projects.list, client.workspaces.list, client.entities.list).

Filter syntaxes¶

CLI dot flags¶

Generated CLI list commands expose each simple filter field as its own option:

nemo evaluation benchmarks list --filter.name mmlu --filter.project my-project

Dot flags cover exact-match on scalar fields. For operators ($gte, $like, …) or boolean combinations, fall through to --filter with text or JSON:

nemo evaluation benchmarks list --filter 'name:"mmlu" AND created_at>="2025-01-01"'
nemo evaluation benchmarks list --filter '{"created_at":{"$gte":"2025-01-01"}}'

Bracket notation¶

The preferred form for REST query strings. Each ?filter[field][$op]=value pair is URL-encoding-friendly and composable:

GET /v2/workspaces/{ws}/benchmarks?filter[name][$like]=mmlu&filter[created_at][$gte]=2025-01-01

When no operator is specified, the default is $eq:

?filter[name]=mmlu # equivalent to filter[name][$eq]=mmlu

Note

On datetime fields, bare bracket values also default to $eq — ?filter[created_at]=2025-01-01 matches only rows whose timestamp equals 2025-01-01 exactly, which is rarely what you want. Use an explicit comparison operator ($gte, $lte, $gt, $lt) for datetime fields.

Text syntax¶

A compact, human-readable query string. Handy for CLI and SDK string filters; in URLs you need to URL-encode spaces and quotes, so bracket notation is usually easier there.

nemo evaluation benchmarks list --filter 'name:"mmlu" AND created_at>"2025-01-01"'

projects = client.projects.list(filter='name~"eval" AND created_at>"2025-01-01"')

Text operators:

Operator	Meaning	Example
`:`	Exact match (case-sensitive)	`name:"mmlu"`
`~`	Substring match (case-insensitive)	`name~"llam"`
`>`	Greater than	`created_at>"2025-01-01"`
`>=`	Greater than or equal	`created_at>="2025-01-01"`
`<`	Less than	`updated_at<"2025-12-31"`
`<=`	Less than or equal	`updated_at<="2025-12-31"`
`IN`	Value in list	`status IN ["active", "pending"]`
`NOT IN`	Value not in list	`status NOT IN ["deleted"]`
`-`	Negation (prefix)	`-status:"draft"`

Combine conditions with AND, OR, and parentheses:

name~"llama" AND (status:"active" OR status:"pending")

Spaces between conditions are treated as implicit AND.

String values must be double-quoted.

JSON¶

Pass a dictionary to the filter parameter. Keys are field names; values are either a literal (for exact match) or an operator object. This form is most useful when building queries programmatically:

# Exact match
results = client.evaluation.benchmarks.list(filter={"name": "mmlu"})

# Operator syntax
results = client.evaluation.benchmarks.list(filter={"name": {"$like": "mmlu"}})

# Multiple conditions
results = client.evaluation.benchmarks.list(
    filter={
        "$and": [{"name": {"$like": "mmlu"}}, {"description": {"$like": "reasoning"}}]
    }
)

# Date range
results = client.evaluation.benchmarks.list(
    filter={
        "created_at": {"$gte": "2025-01-01T00:00:00", "$lte": "2025-06-30T23:59:59"}
    }
)

When a bare value is provided (without an operator object), it defaults to $eq:

# These are equivalent
client.files.filesets.list(filter={"purpose": "dataset"})
client.files.filesets.list(filter={"purpose": {"$eq": "dataset"}})

Operators reference¶

Operator	Meaning	Example (JSON)
`$eq`	Exact match (case-sensitive)	`{"name": {"$eq": "mmlu"}}`
`$like`	Substring match (case-insensitive)	`{"name": {"$like": "mmlu"}}`
`$lt`	Less than	`{"created_at": {"$lt": "2025-06-01"}}`
`$lte`	Less than or equal	`{"created_at": {"$lte": "2025-06-01"}}`
`$gt`	Greater than	`{"created_at": {"$gt": "2025-01-01"}}`
`$gte`	Greater than or equal	`{"created_at": {"$gte": "2025-01-01"}}`
`$in`	Value in set	`{"status": {"$in": ["active", "pending"]}}`
`$nin`	Value not in set	`{"status": {"$nin": ["deleted"]}}`
`$and`	Logical AND	`{"$and": [{"name": "a"}, {"status": "active"}]}`
`$or`	Logical OR	`{"$or": [{"name": "a"}, {"name": "b"}]}`
`$not`	Logical NOT	`{"$not": {"status": "draft"}}`

Nested fields¶

The API supports filtering on nested data.* fields (e.g., custom labels). These fields aren't part of the typed filter model, so use extra_query with bracket notation to pass them through:

# Filter by a custom label
benchmarks = client.evaluation.benchmarks.list(
    extra_query={"filter[data.labels.eval_category]": "agentic"}
)

The equivalent REST call:

?filter[data.labels.eval_category]=agentic

Common patterns¶

Date range¶

results = client.evaluation.metrics.list(
    filter={
        "created_at": {"$gte": "2025-01-01T00:00:00", "$lte": "2025-06-30T23:59:59"}
    }
)

Substring match¶

models = client.models.list(filter={"name": {"$like": "llama"}})

Multiple conditions¶

metrics = client.evaluation.metrics.list(
    filter={"$and": [{"name": {"$like": "bleu"}}, {"type": "llm-as-a-judge"}]}
)

Filtering by status¶

jobs = client.customization.jobs.list(filter={"status": "completed"})