> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Outputs

> Contextual AI How-to Guide

Contextual AI supports structured outputs in JSON format. Use structured output mode when responses must follow a consistent, easily parsed format—for example, to extract defined data fields or integrate with downstream applications and workflows.

<Info>
  This feature is currently in beta, with attributions and other capabilities planned for future release.
</Info>

To use structured outputs:

1. Define your schema, which must be valid JSON and include the `json_schema` key.
   <CodeGroup>
     ```python Python theme={null}
     # define schema
     schema = {
      "json_schema": {
             "type": "object",
             "properties": {
                 "regions": {
                     "type": "array",
                     "items": {
                         "type": "object",
                         "properties": {
                             "region": {"type": "string"},
                             "revenue": {"type": "number"},
                             "share_of_revenue": {"type": "number"}
                         },
                         "required": ["region", "revenue", "share_of_revenue"]
                     }
                 }
             },
             "required": ["regions"]
         }
     }
     ```
   </CodeGroup>
2. Pass the schema as part of your `/query` request.

<Note>
  [Contextual AI Python SDK](https://github.com/ContextualAI/contextual-client-python) users must include the schema under the `structured_output` key in the `extra_body` parameter.
</Note>

<CodeGroup>
  ```python Python SDK theme={null}
  from contextual import ContextualAI
  # initialize your client
  client = ContextualAI(
      api_key=os.environ.get("CONTEXTUAL_API_KEY"),
  )
  # define your schema and add it to the payload object under the
  # structured_output key
  payload = {
      "structured_output": schema
  }
  # pass the payload in the "extra_body" field, along with your other
  # query parameters
  response = client.agents.query.create(
  	# replace with your agent's id
  	agent_id="",
  	# replace with your query
  	messages=[{"content": "what was the regional revenue breakdown in 2022", "role": "user"}],
  	# pass the schema in the `extra_body` param
  	extra_body=payload
  )
  ```
</CodeGroup>

3. Parse the returned message as JSON-formatted data:
   <CodeGroup>
     ```python Python theme={null}
     import json
     results = json.loads(response.message.content)
     ```
   </CodeGroup>

The resulting structured output can then be used for a variety of downstream applications:

```json theme={null}
{'regions': [{'region': 'Americas',
   'revenue': 28079,
   'share_of_revenue': 44.0},
  {'region': 'Europe, Middle East & Africa',
   'revenue': 25301,
   'share_of_revenue': 39.5},
  {'region': 'Asia & Pacific', 'revenue': 10486, 'share_of_revenue': 16.4}]}
```