# Structure the output

By default a run returns one block of text when it finishes. When a downstream system has to consume the result, free-form prose is hard to work with — you end up writing brittle parsers. Structured output makes the model return JSON that conforms to a schema you define, so you can deserialize it directly. For the exhaustive reference — streaming, background runs, error handling, and full schema examples — see [Output Control](/guides/agent-api-output-control).

## Structured output

Set `response_format` to a `json_schema` with a `name` and a `schema`. The response text conforms to the schema unless generation is cut short. The example below builds the schema from a Pydantic model and validates the response against it:

:::code-group
```python Python theme={null}
from typing import List, Optional
from pydantic import BaseModel
from perplexity import Perplexity

class CompanySummary(BaseModel):
    name: str
    sector: str
    headquarters: str
    key_products: Optional[List[str]] = None

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Summarize NVIDIA: sector, headquarters, and key products.",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "company_summary",
            "schema": {
                **CompanySummary.model_json_schema(),
                "required": list(CompanySummary.model_fields.keys()),
                "additionalProperties": False,
            },
        },
    },
)

summary = CompanySummary.model_validate_json(response.output_text)
print(summary.name, summary.sector)
```

```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Summarize NVIDIA: sector, headquarters, and key products.",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "company_summary",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "sector": { "type": "string" },
            "headquarters": { "type": "string" },
            "key_products": { "type": "array", "items": { "type": "string" } }
          },
          "required": ["name", "sector", "headquarters"]
        }
      }
    }
  }' | jq
```
:::

:::callout{intent="tip"}
Reinforce the schema in your prompt ("Return the data as a JSON object matching the schema") to improve adherence.
:::

:::callout{intent="warning"}
Avoid asking for links inside the JSON. A model emitting URLs as part of structured output can produce malformed or fabricated links. Pull links from the `citations` or `search_results` items in the response `output` instead.
:::

## Next steps

::::card-grid
:::card{title="Keep context" href="/guides/agent-api-building-agents-keep-context" icon="link"}
Carry state across multiple turns.
:::

:::card{title="Output Control" href="/guides/agent-api-output-control" icon="sliders"}
Streaming, background runs, error handling, and full structured-output examples.
:::
::::

## Related pages

- [Define the run](./agent-api-building-agents-define-the-run.md)
- [Prompt the agent](./agent-api-building-agents-prompt-the-agent.md)
- [Give it tools](./agent-api-building-agents-give-it-tools.md)
- [Run code](./agent-api-building-agents-run-code.md)
- [Keep context](./agent-api-building-agents-keep-context.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.