Filter a Studio

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:

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.

Dataset Studio Explore view with Primary Action set to pick_grasp and Hands Used set to both, alongside a matching clip

Filter and refine

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

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:

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

Groups can nest:

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:

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.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Filter a Studio

Filter and refine

​Filter and refine

Filter and refine