Dataset Studio quickstart

Dataset Studio helps you go from thousands of recordings to a curated set of relevant events. Search across multimodal data using natural language, inspect matching moments, and classify events with custom taxonomies to build datasets for analysis and evaluation. This guide takes a robot-action batch through the core workflow. You’ll create a Studio, find a grasp, label actions, and review the filtered clips. The same steps apply to other processed datasets. Before you start, have:

A Nomadic API key with write access.
A Nomadic public example batch, used below. You can also run your own batch and use its ID.

1. Install and connect

pip install -U nomadic pydantic

import os
from getpass import getpass
from typing import Literal

from nomadic import NomadicAI
from pydantic import BaseModel, Field

api_key = os.environ.get("NOMADIC_API_KEY")
if not api_key:
    api_key = getpass("Nomadic API key: ")
client = NomadicAI(api_key=api_key)

# Public robot-action example batch.
BATCH_ID = "aa1dbff79fb64c2a9f8a6bb92d322894"

2. Create a Studio

Run this once: each call creates a new Studio from the completed batch. It reuses the batch’s videos and analysis events.

studio = client.studio.create_from_batch(
    BATCH_ID,
    title="Robot actions — SDK walkthrough",
)
print("Studio ID:", studio.id)
print("Videos:", studio.video_count)
print("Open Studio:", studio.url)

Open studio.url to explore the same dataset in the app. See Create a Studio for multiple batches and folders.

3. Find and watch an event

Deep Search returns ranked matches. Search can take longer on a new Studio while its index is preparing; the SDK prints progress during that wait.

matches = client.studio.search(
    studio.id,
    "robot gripper picks up or moves an object",
    top_k=5,
)
print(matches)

if matches.first(1):
    matches.visualize(max_videos=3)  # Plays matching clips in a notebook.

Try another query if no matches appear. Search results are a ranked selection, not every occurrence in the footage. See Search a Studio for result properties and limits. Here is one match from the notebook run. The result points to the source video at 0.0–1.2 seconds, where a robot grasps and lifts a marker. Run matches.visualize() to play the clip and inspect its event details.

Notebook result showing a robot-arm video matched by Dataset Studio search

Video ID: 0e5a89c8cd304fc1a79ab941c22b1b64
Match: The robot closes its gripper around a marker and lifts it from the table.

4. Add a taxonomy

Deep Search helps you discover relevant moments, while taxonomies assign structured labels across the Studio so you can consistently filter and curate events. This example adds an action category and a true/false gripper field. The run classifies events in the background; wait() shows progress as each field becomes available.

class RobotAction(BaseModel):
    robot_action: Literal["grasp", "move", "place"] = Field(
        description="Visible robot action: grasp, move, or place"
    )
    gripper_closed: bool = Field(
        description="Whether the gripper is closed around an object"
    )

run = client.studio.add_taxonomy(studio.id, RobotAction)
run.wait()
print("Final status:", run.status)

Use Add a taxonomy for other field types and for what a completed run does—and does not—guarantee. If you rerun this cell on the same Studio, you may get a duplicate-field error.

5. Narrow and review the results

The new labels let you find all events classified as grasps, then narrow that set to grasps where the gripper is closed. Play a few clips to check the results before using them in a dataset.

grasping = client.studio.filter(
    studio.id, filters={"robot_action": "grasp"}
)
closed_grasps = grasping.filter(
    filters={"gripper_closed": True}
)

print("Grasp events:", grasping.total)
print("Grasps with a closed gripper:", closed_grasps.total)
if closed_grasps.first(1):
    closed_grasps.visualize(max_videos=3)

For fields you did not define yourself, use client.studio.taxonomy_schema(studio.id) to see their names and values. See Filter a Studio for more ways to combine conditions.

Keep exploring

Create from other sources

Build a Studio from multiple batches or existing folders.

Search and inspect events

Refine a query and inspect the events and source clips it returns.

Combine taxonomy filters

Discover fields and narrow results with AND/OR conditions.

Export selected events

Curate events and download their media and MCAP sessions.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Dataset Studio quickstart

1. Install and connect

2. Create a Studio

3. Find and watch an event

4. Add a taxonomy

5. Narrow and review the results

Keep exploring

Create from other sources

Search and inspect events

Combine taxonomy filters

Export selected events

​1. Install and connect

​2. Create a Studio

​3. Find and watch an event

​4. Add a taxonomy

​5. Narrow and review the results

​Keep exploring

Create from other sources

Search and inspect events

Combine taxonomy filters

Export selected events

1. Install and connect

2. Create a Studio

3. Find and watch an event

4. Add a taxonomy

5. Narrow and review the results

Keep exploring