Chat Completions vs Responses API: Comparison

Two endpoints, two philosophies

xAI offers two endpoints for interacting with Grok models: Chat Completions (/v1/chat/completions) and the Responses API (/v1/responses). Understanding their differences is essential for choosing the right endpoint for your project and planning any potential migration.

State management: the fundamental difference

Chat Completions: you manage the history

With every request, you must resend the entire conversation:

# Chat Completions — resend everything every time
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! How can I help you?"},
        {"role": "user", "content": "What is my first name?"}
    ]
)

Responses API: the server manages the history

With the Responses API, a simple identifier is enough to continue a conversation:

# Responses API — just the previous response ID
response1 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Hello, my name is Alice."
)

response2 = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What is my first name?",
    previous_response_id=response1.id
)

The server keeps the context and reconstructs the history automatically. You don’t pay fewer tokens (the history is still billed), but you simplify your code and reduce the size of your requests.

Exclusive tools and features

The Responses API gives access to server tools that Chat Completions does not offer:

• web_search: real-time web search
• x_search: search within X (Twitter) posts
• code_interpreter: server-side Python code execution

These tools are integrated directly into the request:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What is the latest news on AI?",
    tools=[{"type": "web_search"}]
)

Chat Completions supports function calling (developer-defined tools), but not these server tools managed by xAI.

When to use Chat Completions?

Chat Completions remains the right choice in several scenarios:

• Migration from OpenAI: your existing code works without major modification
• Multi-provider: you want to switch between OpenAI, Anthropic, and xAI with the same code
• Third-party frameworks: LangChain, LlamaIndex, Haystack, and most frameworks use the Chat Completions format
• Full control: you want to manage the history yourself (summarization, filtering, modification)

When to use the Responses API?

The Responses API is preferable for:

• New projects: benefit from the latest features from the start
• Server tools: need web search, code execution, or X search
• Long conversations: no need to resend history with every request
• Encrypted reasoning: access to reasoning content for continuity between requests

Key takeaways

• Chat Completions is stateless (you manage history), the Responses API is stateful (server manages)
• The Responses API offers exclusive server tools: web_search, x_search, code_interpreter
• Chat Completions has full OpenAI compatibility, the Responses API is specific to xAI
• Both endpoints bill for the full conversation history
• Use Chat Completions for compatibility, the Responses API for new features