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: An exact filter returns events already labeled with those values; it does not run a new detector over every source video. Conditions from different analyses can match through positive time overlap on the same video. Such a join is a co-occurrence of analysis intervals, not proof that both fields were directly observed on one event or that one caused the other.

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. Numeric taxonomy fields support strict thresholds and equality. The field must contain numbers, such as speed_mps, rather than category labels:

slow = client.studio.filter(studio_id, filters={"speed_mps": "< 5"})
fast = client.studio.filter(studio_id, filters={"speed_mps": "> 20"})
stationary = client.studio.filter(studio_id, filters={"speed_mps": "= 0"})

The supported operators are <, >, and =. Boolean fields accept Python True and False, which can be combined with numeric or categorical filters:

# Strictly between 5 and 15; neither boundary is included.
mid_speed = client.studio.filter(
    studio_id,
    where={"and": [{"speed_mps": "> 5"}, {"speed_mps": "< 15"}]},
)

slow_motion = client.studio.filter(
    studio_id, filters={"speed_mps": "< 5", "is_moving": True}
)

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.

Reading large result sets

total is the match count for the filter response. Iteration requests later pages automatically, up to the current Studio event table. Pagination uses offsets, not a snapshot token: if batches or taxonomy values change while you iterate, restart the filter before treating the collected rows as a stable export set. The SDK does not expose a resume cursor for an interrupted iteration. Preserve event.event_id when deduplicating results across independent runs; video_id alone can group several distinct events. Check client.studio.facet_rows(studio_id).get("truncated") before relying on coverage of a large Studio. A successful exact filter enumerates labeled matches in that event table; it cannot guarantee the source analysis labeled every physical occurrence.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Filter a Studio

Filter and refine

Reading large result sets

​Filter and refine

​Reading large result sets

Filter and refine

Reading large result sets