Structured output

Overview

To get an Agent run’s answer as a JSON object matching your own schema instead of freeform Markdown, request structured output by passing a schema when you start the run.

Provide a schema

Pass output_schema (an OpenAI-style response_format object) to get output.structured, a JSON result shaped by your schema, in addition to the usual cited output.text report.

OUTPUT_SCHEMA = {
    "type": "json_schema",
    "json_schema": {
        "name": "acquisitions",
        "schema": {
            "type": "object",
            "properties": {
                "acquisitions": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "acquirer": {"type": "string"},
                            "target": {"type": "string"},
                        },
                        "required": ["acquirer", "target"],
                        "additionalProperties": False,
                    },
                },
            },
            "required": ["acquisitions"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

run = client.agent.create_and_wait(
    "What are three notable AI-company acquisitions announced in 2026?",
    output_schema=OUTPUT_SCHEMA,
)

import json

result = json.loads(run.output.structured)
for deal in result["acquisitions"]:
    print(deal["acquirer"], "->", deal["target"])

const outputSchema = {
  type: "json_schema",
  json_schema: {
    name: "acquisitions",
    schema: {
      type: "object",
      properties: {
        acquisitions: {
          type: "array",
          items: {
            type: "object",
            properties: {
              acquirer: { type: "string" },
              target: { type: "string" },
            },
            required: ["acquirer", "target"],
            additionalProperties: false,
          },
        },
      },
      required: ["acquisitions"],
      additionalProperties: false,
    },
    strict: true,
  },
};

const run = await client.agent.createAndWait({
  query: "What are three notable AI-company acquisitions announced in 2026?",
  outputSchema,
});

const result = JSON.parse(run.output!.structured!);
for (const deal of result.acquisitions) {
  console.log(deal.acquirer, "->", deal.target);
}

curl -X POST https://api.seltz.ai/v1/agent/runs \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are three notable AI-company acquisitions announced in 2026?",
    "output_schema": {
      "type": "json_schema",
      "json_schema": {
        "name": "acquisitions",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "acquisitions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "acquirer": {"type": "string"},
                  "target": {"type": "string"}
                },
                "required": ["acquirer", "target"],
                "additionalProperties": false
              }
            }
          },
          "required": ["acquisitions"],
          "additionalProperties": false
        }
      }
    }
  }'

A completion for the request above looks like this:

{
  "acquisitions": [
    { "acquirer": "SpaceX", "target": "Anysphere (Cursor)" },
    { "acquirer": "Zendesk", "target": "Forethought" },
    { "acquirer": "Palo Alto Networks", "target": "Console" }
  ]
}

The matching output.grounding looks like the following, one entry per groundable field, each citing back into output.sources by source_id:

[
  {
    "field": "acquisitions.0.acquirer",
    "citations": [{ "source_id": 1, "url": "https://www.latestly.com/technology/spacex-to-acquire-ai-coding-startup-cursor-in-usd-60-billion-deal-7475967.html" }]
  },
  {
    "field": "acquisitions.0.target",
    "citations": [{ "source_id": 1, "url": "https://www.latestly.com/technology/spacex-to-acquire-ai-coding-startup-cursor-in-usd-60-billion-deal-7475967.html" }]
  }
]

Schema validity

Create validates output_schema’s wrapper shape, including type, and json_schema.name / schema / strict for type json_schema, before billing anything, and rejects a malformed one there. It does not validate the schema’s content. For strict: true, every object in the schema needs its own additionalProperties: false, including nested ones like the array item object above. Create accepts a schema missing it, but the run then fails with stop_reason: invalid_output.

Results

A run that produces no JSON output at all fails with stop_reason: invalid_output rather than returning something unparsable. Ungroundable fields come back null in output.structured. This is the same “don’t guess” contract Answer follows.

Next steps

Basic run: the full request/response cycle, including the cURL poll
Handle errors: rejected requests versus failed runs
Reference: endpoints, fields, limits and errors
Agent API Reference: full output_schema request and response specification

Getting Started

Web Tools

Data

Tutorials

Integrations

SDKs

Structured output

Overview

Provide a schema

Schema validity

Results

Next steps

​Overview

​Provide a schema

​Schema validity

​Results

​Next steps

Overview

Provide a schema

Schema validity

Results

Next steps