A simple POST /v1/responses request

Updated November 3, 2026, based on the xAI best practices and API reference: temperature is capped at 1, and xAI recommends 0.7 with top_p at 0.95. Source: Best practices.

Your first successful call

You have your account, your API key, and an SDK installed. It’s time to send your first request to the Grok API and understand the structure of the response. This lesson focuses on the main endpoint, /v1/responses, the most modern and most recommended one.

Request structure

The POST /v1/responses endpoint takes at least two parameters:

• model: the ID of the model to use
• input: the text of your request (or an array of content for advanced cases)

Minimal request in Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.5",
    input="What's the most widely used programming language in 2026?"
)

print(response.output[0].content[0].text)

With system instructions

The instructions parameter lets you define the model’s behavior:

response = client.responses.create(
    model="grok-4.5",
    instructions="You are a web development expert. Answer concisely.",
    input="What's the difference between SSR and SSG?"
)

Anatomy of the response

The API returns a structured JSON object. Here are the main fields:

{
  "id": "resp-abc123",
  "object": "response",
  "status": "completed",
  "model": "grok-4.5",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The model's answer appears here."
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156,
    "total_tokens": 198
  }
}

Important fields

• id: the response’s unique ID, useful for retrieving it later
• status: completed when generation is finished
• output: an array containing the generated messages
• usage: token counters for tracking your consumption

Common optional parameters

Control creativity

response = client.responses.create(
    model="grok-4.5",
    input="Suggest a name for an AI startup.",
    temperature=0.7,  # the value xAI recommends
    top_p=0.95,
)

• The API accepts a temperature from 0 to 2, but caps any higher value at 1
• xAI recommends temperature=0.7 and top_p=0.95 and advises against straying from them: quality usually drops
• For more creativity, ask for it in the prompt (“suggest unexpected names”)

Limit the length

response = client.responses.create(
    model="grok-4.5",
    input="Summarize the concept of machine learning.",
    max_output_tokens=200  # Caps the answer
)

Turn on reasoning

For reasoning models, adjust the thinking effort:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this problem: if 3x + 7 = 22, what is x?",
    reasoning={"effort": "high"}
)

The possible levels are low, medium, and high.

Continue a conversation

The /v1/responses endpoint supports multi-turn conversations through the previous_response_id parameter:

# First message
r1 = client.responses.create(
    model="grok-4.5",
    input="I'm building an API in Python."
)

# Second message (the model remembers the context)
r2 = client.responses.create(
    model="grok-4.5",
    input="Which framework do you recommend?",
    previous_response_id=r1.id
)

This approach is simpler than managing the message history yourself.

Track costs

The usage field in the response lets you calculate the cost of each call. The output_tokens_details.reasoning_tokens field shows how many tokens went into the model’s internal reasoning (these tokens are billed but don’t appear in the answer).

Key takeaways

• The POST /v1/responses endpoint is the most modern and most recommended
• Two required parameters: model and input
• The answer is in output[0].content[0].text
• Use previous_response_id for multi-turn conversations
• The usage field helps you track your token consumption