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

# Structured Output

> Define a schema for your video analysis and read typed results

Define the fields your analysis should return instead of parsing free text.
Use the resulting batch to [create a Studio](/sdk/create-studio) with the same
schema as its taxonomy.

## Define and run

Install `nomadic`, `pydantic`, and `pandas`, then define your schema:

```python theme={null}
import os
from typing import Literal

from pydantic import BaseModel
from nomadic import NomadicAI

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


class RoadScene(BaseModel):
    weather: Literal["clear", "rain", "snow", "fog"]
    lighting: Literal["day", "night", "twilight"]


batch = client.analyze(
    ["VIDEO_ID_1", "VIDEO_ID_2"],
    "Identify road scenes and classify their weather and lighting.",
    output_schema=RoadScene,
)
```

The SDK validates the schema locally before sending the request. Prompt
analysis supports structured output in the default `mode="thinking"`, not
`mode="fast"`.

## Read results

Get typed objects or a pandas table:

```python theme={null}
for scene in batch.structured(as_model=RoadScene):
    print(scene.weather, scene.lighting)

frame = batch.to_dataframe(only_structured=True)
print(frame[["video_id", "event_id", "weather", "lighting"]])
```

`structured()` without `as_model` returns dictionaries. Both examples skip
events without a structured payload. DataFrame rows include event metadata
alongside your schema fields; only the DataFrame helper requires pandas.

Fetch an existing batch with `client.video.get_batch_analysis("BATCH_ID")` to
use the same helpers.

## Other schema formats

Without Pydantic, pass a list of field definitions as `output_schema`:

```python theme={null}
schema = [
    {"name": "weather", "type": "enum", "values": ["clear", "rain", "snow", "fog"]},
    {"name": "lighting", "type": "enum", "values": ["day", "night", "twilight"]},
]
```

Supported types are `enum`, `text`, `number`, `boolean`, and `time_range`.
Schemas support up to 12 fields; enums require 2–64 distinct values. Use unique
snake\_case names, `required=False` for optional fields, and `repeated=True` for
multiple values.

Next: [Create a Studio](/sdk/create-studio).


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