---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

title: "Filtering"
description: ""
---

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:

```bash
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:

```bash
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
```

<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.

</Note>
### 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.

```bash
nemo files filesets list --filter 'purpose:"dataset" AND created_at>"2025-01-01"'
```

```python
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:

```python
# Exact match
results = client.files.filesets.list(filter={"purpose": "dataset"})

# Operator syntax
results = client.files.filesets.list(filter={"name": {"$like": "training"}})

# Multiple conditions
results = client.files.filesets.list(
    filter={
        "$and": [{"purpose": "dataset"}, {"description": {"$like": "training"}}]
    }
)

# Date range
results = client.files.filesets.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`:

```python
# 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 labels via `extra_query` with bracket notation:

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

The equivalent REST call:

```
?filter[labels.eval_category]=agentic
```

## Common patterns

### Date range

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

### Substring match

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

### Multiple conditions

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

### Filtering by status

```python
jobs = client.jobs.list(
    workspace="default",
    filter={"source": "automodel", "status": "completed"},
)
```
