Search a Studio

Deep Search finds events in a Studio from a plain-language query, using the same search experience as the app. You need a Studio ID and an API key that can access it. Create a Studio if you do not have one yet.

Deep Search ranks events retrieved as candidates; it does not scan or certify every occurrence in the source footage. top_k, reranking, and candidate generation can all limit recall. For every event already labeled with a value, use exact taxonomy filtering and iterate its pages. Even that cannot find occurrences the original analysis missed.

import os
from nomadic import NomadicAI

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

results = client.studio.search(
    studio.id,
    "a forklift passing close to a pedestrian",
    top_k=25,
)

results  # In a notebook; use print(results) in a script.

The result displays each match with a video ID, description, and timestamps when available. Missing timestamps are omitted. results is a collection, so access video_id on an individual event, not on results:

for event in results:
    print(event.video_id, event.description)
    if event.start_time is not None:
        print("Starts at:", event.start_time, "seconds")

first = results.first(1)  # Returns a list; empty when there are no matches.
if first:
    print(first[0].video_id)

video_ids = [event.video_id for event in results]

Object	Property	Meaning
`results`	`total`	Number of matches returned by Deep Search.
`results`	`candidate_count`	Size of the retrieval pool before reranking; candidates are not necessarily matches.
`event`	`video_id`	Source video’s ID.
`event`	`start_time`, `end_time`	Event timestamps in seconds; either may be `None`. `0.0` means the beginning of the video, not zero confidence.
`event`	`description`	Event description.
`event`	`score`, `match_reason`	Rerank score and short reason, when available. A score may be absent on a fallback result.
`event`	`relevance`	Display tier derived from the score: `Strong match`, `Good match`, `Related`, or `None` when no rerank tier is available.

Each event is also a dictionary: event["video_id"] is equivalent to event.video_id. Use event.get("end_time") for an optional field. To inspect all fields returned for a particular event, use dict(first[0]) after checking that first is nonempty. Deep Search returns the reranker’s selected matches. Like the app, the SDK does not hide lower-scoring returned matches. When a rerank score is available, the display labels it Strong match (0.75+), Good match (0.5+), or Related (below 0.5). To select only strong matches in code:

strong = [event for event in results if event.relevance == "Strong match"]

score is a model relevance score for this query, not a calibrated probability that the event occurred. The display tiers are presentation thresholds, not accuracy guarantees. Do not compare scores across different queries or model versions as if they shared a calibrated scale. For a quality threshold, review a labeled sample against the source footage and measure precision for your own use case. If a newly created Studio returns no events while its search index is starting, queued, or building, search() retries every 10 seconds and prints status updates in plain language. You may see “Searching your Studio… New datasets can take a few minutes to prepare.” It returns as soon as matches are available or the index is ready. After three minutes, it raises TimeoutError with a message to try again in a few minutes. A ready index with no matches returns an empty result normally. Set timeout=300 to wait longer, show_progress=False to silence updates, or wait_for_index=False to return the first response without polling. Refining a result with results.filter(...) keeps these wait settings. Iteration returns the ranked matches in this response. top_k defaults to 50 and can be at most 1,000; search results do not paginate beyond it. Check results["truncated"] to see whether the reranker or response limit left candidate matches unexamined or undisplayed. False does not certify that candidate retrieval found every real-world occurrence. Use results.first(10) when you only need a sample.

Setting or result	Behavior
`top_k`	Maximum returned ranked matches, 1–1,000; no search pagination.
`candidate_count`	Retrieved candidates before deep reranking, not confirmed matches.
`results["truncated"]`	Indicates a known shortlist or response cap; refine the query before treating the returned matches as complete.
`wait_for_index=True`	Retries a temporarily empty response while the index reports that it is starting, queued, or building.
`timeout=180`	Maximum seconds to wait for the index; a timeout leaves the Studio intact.
`show_progress=True`	Prints plain-language status while waiting.
Empty result with ready index	No matches were returned for that query; it is not proof that the scenario is absent from the footage.

Refine by taxonomy

Add an exact taxonomy condition to the same search. This sends a new request; the original results stays available. The condition is applied before Deep Search reranks the matching events.

refined = results.filter(filters={"hands_used": "both"})

for event in refined:
    print(event.video_id, event.start_time)

See Filter a Studio to discover available fields and values, combine AND/OR conditions, and iterate through all exact matches.

Watch the matches

In a notebook, display the matching videos and click an event to play from its timestamp when available:

results.visualize()

In a script, save the viewer and open the file in a browser:

results.visualize(display=False, output_path="studio-matches.html")

Playback is optional. visualize() requests short-lived video URLs only when you call it, and shows the first 10 matching videos by default. Pass max_videos=5 to show fewer. Saved viewers need fresh URLs after 15 minutes; run visualize() again to refresh them. Video playback requires access to the source videos.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Search a Studio

Refine by taxonomy

Watch the matches

​Refine by taxonomy

​Watch the matches

Refine by taxonomy

Watch the matches