> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomadicml.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter a Studio

> Discover taxonomy fields and refine exact event matches

Use your Studio's taxonomy to find events by exact field values. Get the Studio
ID from its URL, then list every available field and value:

```python theme={null}
import os
from nomadic import NomadicAI

client = NomadicAI(api_key=os.environ["NOMADIC_API_KEY"])
studio_id = "STUDIO_ID"

schema = client.studio.taxonomy_schema(studio_id)
for field in schema["fields"]:
    print(field["name"], field["values"])
```

The full value lists are returned; nothing is abbreviated. For example, one
Studio might have `primary_action` values such as `pick_grasp` and
`place_position`, and `hands_used` values `both`, `left`, `right`, and
`unspecified`. Your Studio's schema is the source of truth.

In this example, `primary_action` describes what happens in a clip:
`pick_grasp` means someone picks up an object. `hands_used` identifies the
hands involved. The Explore view below selects `pick_grasp` and `both`, and
shows a matching clip with those labels. Your Studio may have different fields
and values.

<img src="https://mintcdn.com/nomadicmlinc/UrXpwKyfe88wVGNZ/screenshots/dataset-studio-taxonomy-example.png?fit=max&auto=format&n=UrXpwKyfe88wVGNZ&q=85&s=ebad6ce263f2a8fcf32eba03f4d16799" alt="Dataset Studio Explore view with Primary Action set to pick_grasp and Hands Used set to both, alongside a matching clip" width="1280" height="720" data-path="screenshots/dataset-studio-taxonomy-example.png" />

## Filter and refine

Fields in `filters` are joined with AND. A list of values for one field means
OR within that field:

```python theme={null}
results = client.studio.filter(
    studio_id,
    filters={"primary_action": "pick_grasp"},
)

print(results.total)
refined = results.filter(filters={"hands_used": "both"})
for event in refined:
    print(event.video_id, event.start_time, event.end_time)
```

`refined` means `pick_grasp AND both`, matching the screenshot, without changing
`results`. Pass `["left", "both"]` for `left OR both`. Exact-filter
iteration fetches subsequent pages as needed. Use `results.first(20)` for a
small sample, or set `page_size` (1–500) to control request size.

For OR across fields, use `where`:

```python theme={null}
results = client.studio.filter(
    studio_id,
    where={"or": [
        {"primary_object": "blocks_puzzles"},
        {"hands_used": "both"},
    ]},
)
```

Groups can nest:

```python theme={null}
results = client.studio.filter(
    studio_id,
    where={"and": [
        {"primary_action": "pick_grasp"},
        {"or": [
            {"primary_object": "blocks_puzzles"},
            {"hands_used": "both"},
        ]},
    ]},
)
```

For a repeated field, `all_of` requires every listed value:

```python theme={null}
results = client.studio.filter(
    studio_id,
    where={"and": [
        {"all_actions": {"all_of": ["pick_grasp", "place_position"]}},
        {"hands_used": "both"},
    ]},
)
```

To refine a natural-language search with taxonomy values, see
[Search a Studio](/sdk/studio-search).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.