Grok API
  1. Guides
Grok API
  • Getting started
    • Introduction
    • Models and Pricing
    • Billing
    • Consumption and Rate Limits
    • Usage Explorer
    • Free Credits
  • Guides
    • Asynchronous Requests
    • Image Understanding
    • Structured Outputs
    • Migration from Other Providers
    • Chat
      POST
    • Reasoning
      POST
    • Streaming Response
      POST
    • Deferred Chat Completions
      POST
    • Image Generations
      POST
    • Fingerprint
      POST
  1. Guides

Chat

POST
https://api.x.ai/v1/chat/completions
Text in, text out. Chat is the most popular feature on the xAI API, and can be used for anything from summarizing articles, generating creative writing, answering questions, providing customer support, to assisting with coding tasks.

Prerequisites#

xAI Account: You need an xAI account to access the API.
API Key: Ensure that your API key has access to the chat endpoint and the chat model is enabled.
If you don't have these and are unsure of how to create one, follow the Hitchhiker's Guide to Grok.
You can create an API key on the xAI Console API Keys Page.
Set your API key in your environment:
bashexport XAI_API_KEY="your_api_key"

A Basic Chat Completions Example#

You can also stream the response, which is covered in Streaming Response.
The user sends a request to the xAI API endpoint. The API processes this and returns a complete response.
Response:

Conversations #

The xAI API is stateless and does not process new request with the context of your previous request history.
However, you can provide previous chat generation prompts and results to a new chat generation request to let the model process your new request with the context in mind.
An example message:
{
  "role": "system",
  "content": [{ "type": "text", "text": "You are a helpful and funny assistant."}]
}
{
  "role": "user",
  "content": [{ "type": "text", "text": "Why don't eggs tell jokes?" }]
},
{
  "role": "assistant",
  "content": [{ "type": "text", "text": "They'd crack up!" }]
},
{
  "role": "user",
  "content": [{"type": "text", "text": "Can you explain the joke?"}],
}
By specifying roles, you can change how the the model ingest the content. The system role content should define, in an instructive tone, the way the model should respond to user request. The user role content is usually used for user request or data sent to the model. The assistant role content is usually either in the model's response, or when sent within the prompt, indicating the model's response as part of conversation history.
This strategy to send assistant role content can be used within function calling, in which the model response will invoke a tool call, the user's program responds to the tool call and continues the conversation by appending tool call result to the message. For more details, check out our guide on Function Calling.

Message role order flexibility #

Unlike some models from other providers, one of the unique aspects of xAI API is its flexibility with message roles:
No Order Limitation: You can mix system, user, or assistant roles in any sequence for your conversation context.
Example 1 - Multiple System Messages:
[
{"role": "system", "content": "..."},
{"role": "system", "content": "..."},
{"role": "user", "content": "..."},
{"role": "user", "content": "..."}
]
The model takes multiple system
Example 2 - User Messages First:
{
  "role": "user",
  "content": "..."
},
{
  "role": "user",
  "content": "..."
},
{
  "role": "system",
  "content": "..."
}
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.x.ai/v1/chat/completions' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data-raw '{
        "messages": [
          {
            "role": "system",
            "content": "You are Grok, a chatbot inspired by the Hitchhikers Guide to the Galaxy."
          },
          {
            "role": "user",
            "content": "What is the meaning of life, the universe, and everything?"
          }
        ],
        "model": "grok-3-latest",
        "stream": false,
        "temperature": 0
      }'
Response Response Example
{
  "id": "0daf962f-a275-4a3c-839a-047854645532",
  "object": "chat.completion",
  "created": 1739301120,
  "model": "grok-3-latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The meaning of life, the universe, and everything is a question that has puzzled philosophers, scientists, and hitchhikers alike. According to the Hitchhiker's Guide to the Galaxy, the answer to this ultimate question is simply "42". However, the exact nature of the question itself remains unknown. So, while we may have the answer, the true meaning behind it is still up for debate. In the meantime, perhaps we should all just enjoy the journey and have a good laugh along the way!",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 104,
    "total_tokens": 145,
    "prompt_tokens_details": {
      "text_tokens": 41,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 0
    }
  },
  "system_fingerprint": "fp_84ff176447"
}

Request

Header Params
Content-Type
string 
required
Example:
application/json
Authorization
string 
required
Example:
Bearer {{XAI_API_KEY}}
Body Params application/json
messages
array [object {2}] 
required
role
string 
required
content
string 
required
model
string 
required
stream
boolean 
required
temperature
integer 
required
Examples

Responses

🟢200Success
application/json
Body
id
string 
required
object
string 
required
created
integer 
required
model
string 
required
choices
array [object {3}] 
required
index
integer 
optional
message
object 
optional
finish_reason
string 
optional
usage
object 
required
prompt_tokens
integer 
required
completion_tokens
integer 
required
total_tokens
integer 
required
prompt_tokens_details
object 
required
system_fingerprint
string 
required
Modified at 2025-04-10 08:43:26
Previous
Migration from Other Providers
Next
Reasoning
Built with