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 files filesets list --filter.purpose dataset --filter.storage-type local

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

$
nemo files filesets list --filter 'purpose:"dataset" AND created_at>="2025-01-01"'
$
nemo files filesets 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 /apis/files/v2/workspaces/{workspace}/filesets?filter[purpose]=dataset&filter[created_at][$gte]=2025-01-01

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

?filter[purpose]=dataset # equivalent to filter[purpose][$eq]=dataset

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 files filesets list --filter 'purpose:"dataset" AND created_at>"2025-01-01"'

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

Text operators:

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:

1
# Exact match
2
results = client.files.filesets.list(filter={"purpose": "dataset"})
3
4
# Operator syntax
5
results = client.files.filesets.list(filter={"name": {"$like": "training"}})
6
7
# Multiple conditions
8
results = client.files.filesets.list(
9
    filter={
10
        "$and": [{"purpose": "dataset"}, {"description": {"$like": "training"}}]
11
    }
12
)
13
14
# Date range
15
results = client.files.filesets.list(
16
    filter={
17
        "created_at": {"$gte": "2025-01-01T00:00:00", "$lte": "2025-06-30T23:59:59"}
18
    }
19
)

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

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

Operators reference

Nested fields

The API supports filtering on labels via extra_query with bracket notation:

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

The equivalent REST call:

?filter[labels.eval_category]=agentic

Common patterns

Date range

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

Substring match

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

Multiple conditions

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

Filtering by status

1
jobs = client.jobs.list(
2
    workspace="default",
3
    filter={"source": "automodel", "status": "completed"},
4
)