Structured results

By default a run answers in prose, in result.final_text. Pass an output_schema with the prompt and the run also returns result.extracted in that shape. The run completes only if the result matches the schema.

Write the schema

An output_schema is a JSON Schema that describes the fields and value types you want in result.extracted. For a connected account on a shopping website, this request asks for recent orders as a list of objects:

{
  "prompt": "Find my three most recent orders.",
  "output_schema": {
    "type": "object",
    "properties": {
      "orders": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "number": { "type": "string" },
            "placed_on": { "type": "string" },
            "total": { "type": "number" },
            "status": { "type": "string", "enum": ["processing", "shipped", "delivered"] }
          },
          "required": ["number", "total"]
        }
      }
    },
    "required": ["orders"]
  }
}

When this run completes, result.extracted has an orders array in which every order has at least a number and a total. result.final_text still carries the prose answer.

The rules

The API rejects a schema outside these limits with 400 INVALID_OUTPUT_SCHEMA:

• Object root.
• Objects, arrays, strings, numbers, booleans, and enums. No $ref, formats, or conditionals.
• Depth at most 4.
• At most 16 KiB.

The schema describes shape only. For stricter checks, such as a date format, validate result.extracted on your side.

When the page doesn't have the data

If a required field can't be filled from what the page shows, the run fails with unverified or not_possible rather than inventing a value. Make a field optional if it's sometimes absent on the page.

Without a schema

Leave output_schema out and read result.final_text. result.extracted may still hold whatever the run chose to structure, with no guarantee about its shape, so don't build on it without a schema.

Next steps

Results and evidence explains what WOOL confirms before a run completes.