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

# Search a Studio

> Find events with a natural-language query and watch matching videos

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](/sdk/create-studio) if you do not have one yet.

```python theme={null}
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,
)

for event in results:
    print(event.video_id, event.start_time, event.description)
```

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 more candidates were found. Use
`results.first(10)` when you only need a sample.

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

```python theme={null}
refined = results.filter(filters={"hands_used": "both"})

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

See [Filter a Studio](/sdk/studio-filters) 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:

```python theme={null}
results.visualize()
```

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

```python theme={null}
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.


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