Create a Studio

A Studio organizes videos, analysis events, and taxonomies into a browsable dataset. A video can contain several events, and fields from separate analyses may describe overlapping moments rather than the same observation. New to Dataset Studio? Start with the Dataset Studio Quickstart to create a Studio, search its events, and filter by taxonomy.

Starting point	Use
One completed batch	`create_from_batch(batch, title=...)`
Several completed batches	`create_from_batches([batch_a, batch_b], title=...)`
Existing video folders	`create(title=..., folder_ids=[...])`

create_from_batches is an alias of create_from_batch: passing the same list to either makes the same creation request. A folder-based Studio uses the folder’s videos and eligible completed analyses already associated with them; it does not analyze footage again. In the app, owners can add eligible batches to an existing Studio. The SDK currently has no studio.add_batch() helper.

Create from a batch

Use an API key with write access and a completed batch you can access:

import os
from nomadic import NomadicAI

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

studio = client.studio.create_from_batch(
    "COMPLETED_BATCH_ID",
    title="Road scene evaluation",
)

print(studio.url)

You can also pass the batch returned by the Structured Output example:

studio = client.studio.create_from_batch(
    batch,
    title="Road scene evaluation",
)

The Studio adopts the batch’s output schema as a taxonomy and reuses its classifications, so do not add the same taxonomy again.

Each creation call creates a new Studio. These examples are alternatives, not steps.

Create from multiple batches

studio = client.studio.create_from_batches(
    ["COMPLETED_BATCH_ID_1", "COMPLETED_BATCH_ID_2"],
    title="Combined road scenes",
)

For a multi-query batch, pass the parent ID to include each successful query as its own bucket. Running queries must finish first; failed queries are excluded. After creation, inspect studio["buckets"] and compare its sub_batch_id and query_label entries with the parent’s child queries. A partially successful parent can therefore produce fewer buckets than queries.

Create from folders

studio = client.studio.create(
    title="Fleet road scenes",
    folder_ids=["FOLDER_ID_1", "FOLDER_ID_2"],
)

Provide batches or folders, not both. Creating a Studio organizes existing data; it does not run a new video classification.

Creation is not search readiness

create_from_batch() returns the Studio record and studio.url as soon as creation succeeds. Search indexing may still be starting or building. The SDK does not expose one universal studio.ready state: Deep Search waits and reports index status when needed, while taxonomy runs have their own run.wait() lifecycle. A search timeout means the index was not ready within that wait; it does not undo Studio creation. Retry the search later, and check taxonomy schema or facet availability separately before relying on filters.

The Studio object

Every creation call returns a StudioDataset:

Property	Type	Description
`id`	`str`	Unique Studio ID. Pass it to `get()`, `search()` and `add_taxonomy()`.
`title`	`str`	The title you gave the Studio.
`video_count`	`int`	Number of distinct source video IDs in the Studio membership; a video in two batches is counted once.
`taxonomies`	`list[dict]`	Schemas attached to the Studio, newest last. A schema entry alone does not prove every event has that field or a taxonomy run has completed.
`url`	`str`	Link that opens the Studio in the app.

print(studio.id, studio.title, studio.video_count)
print(studio.taxonomies)

StudioDataset is also a dictionary, so the full API response is available by key, for example studio["buckets"]. Batches can contain several events from the same video. video_count deduplicates video IDs; event-level queries and exports use event IDs and may return several events per video.

Retrieve Studios

studio = client.studio.get(studio.id)

for item in client.studio.list():
    print(item.id, item.title)

get() fetches fresh detail for one Studio. list() returns the Studios you own. Next: Search your Studio or add taxonomies.

Overview

Getting Started

Dataset Studio

Deployment

Advanced

Legal

Create a Studio

Create from a batch

Create from multiple batches

Create from folders

Creation is not search readiness

The Studio object

Retrieve Studios

​Create from a batch

​Create from multiple batches

​Create from folders

​Creation is not search readiness

​The Studio object

​Retrieve Studios

Create from a batch

Create from multiple batches

Create from folders

Creation is not search readiness

The Studio object

Retrieve Studios