Understand the response format

Anatomy of a response

When you send a request to POST /v1/responses, the xAI server returns a structured JSON object. Understanding each field in this object is essential to correctly use the results in your application.

Complete structure

Here is a typical response:

{
  "id": "resp-abc123def456",
  "object": "response",
  "created_at": 1712000000,
  "status": "completed",
  "model": "grok-4.20-0309-reasoning",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Le machine learning est une branche de l'IA...",
          "annotations": []
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 180,
    "total_tokens": 225,
    "output_tokens_details": {
      "reasoning_tokens": 120
    },
    "cost_in_nano_usd": 500000
  }
}

Main fields

id

The unique identifier for the response, in the format resp-xxx. You will use it to:

• Chain conversations with previous_response_id
• Retrieve a stored response with GET /v1/responses/{id}
• Delete a response with DELETE /v1/responses/{id}

status

The status of the response:

Always check the status before using the response content in your code.

output

An array containing the response elements. Each element has a type:

• message: Text response from the model
• function_call: Tool call requested by the model

The text content is located at output[0].content[0].text. Annotations (citations, links) are in the annotations array of the same object.

usage

Usage information, detailed below.

Understand the usage object

The usage object is crucial for tracking your costs:

{
  "input_tokens": 45,
  "output_tokens": 180,
  "total_tokens": 225,
  "output_tokens_details": {
    "reasoning_tokens": 120
  },
  "cost_in_nano_usd": 500000
}

Input and output tokens

• input_tokens: Number of tokens in your prompt (and in the history if chaining conversations)
• output_tokens: Total number of tokens generated, including reasoning
• total_tokens: Sum of both

Reasoning tokens

output_tokens_details.reasoning_tokens indicates how many tokens the model used for its internal reasoning. These tokens are billed but are not visible in the text response.

In the example above, out of 180 output tokens, 120 are for reasoning and only 60 make up the visible response. This is a typical ratio for reasoning models.

Cost in nano-USD

cost_in_nano_usd gives the exact cost of the request. The conversion is simple:

Cost in USD = cost_in_nano_usd / 1,000,000,000

For our example: 500000 / 1,000,000,000 = 0.0005 USD ($0.0005).

Server-side tool usage

When the model uses built-in tools, the usage object also includes:

{
  "server_side_tool_usage_details": {
    "web_search_calls": 2,
    "code_interpreter_calls": 0,
    "x_search_calls": 1,
    "document_search_calls": 0,
    "file_search_calls": 0,
    "mcp_calls": 0
  }
}

This lets you know exactly which tools were invoked and how many times.

Extract text in Python

Here is a robust pattern to extract text content:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explique les listes en Python."
)

# Check status
if response.status == "completed":
    text = response.output[0].content[0].text
    print(text)
else:
    print(f"Error: status {response.status}")

# Display usage
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")

Key takeaways

• Each response has a unique id reusable for chaining or retrieval
• Always check the status before using the content
• The text is located at output[0].content[0].text
• reasoning_tokens are billed but invisible in the response
• cost_in_nano_usd divided by one billion gives the cost in dollars