Grok API Python Tutorial: xAI SDK and Grok 4.7 (2026)

xAI’s Grok API works with the official xai-sdk and with the OpenAI Python SDK, so you can start in minutes. The current flagship, Grok 4.7, arrived on September 21, 2026 with a 500K token context window.

This tutorial covers everything in Python: your API key, both SDKs, streaming, function calling, vision, live web and X search, caching, rate limits and errors.

Step 1: Get a key from console.x.ai

The Grok API is prepaid and separate from X Premium or a SuperGrok plan. You need credits in the xAI Console before any call works.

1. Sign up. Go to console.x.ai and create an account or sign in.
2. Add credits. Load your team with credits. A small top-up is enough to follow this tutorial.
3. Create a key. Open the API Keys page and create a new key.
4. Copy it safely. Store it in a password manager. Treat it like a password.
5. Save it as an environment variable. Or put XAI_API_KEY=your_api_key in a .env file.

# macOS / Linux
export XAI_API_KEY="your_api_key"

# Windows PowerShell
$env:XAI_API_KEY="your_api_key"

Step 2: Pick an SDK and install it

You have two good options. Both call the same models at the same prices.

• xai-sdk: xAI’s own Python SDK. It uses gRPC and has handy helpers for tools, images and search.
• openai SDK: point it at xAI’s base URL. Best if you already have OpenAI code or want to switch providers easily.

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install xai-sdk openai

Create a client with xai-sdk

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Create a client with the OpenAI SDK

import os
from openai import OpenAI

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

Tip: The OpenAI-compatible route supports both the Responses API and Chat Completions. Most tools that accept a custom OpenAI base URL will work with Grok this way.

Grok models and prices

xAI’s docs mark grok-4.7 as the newest text model. It takes text and images as input and returns text.

A few things to know about the lineup:

• Long prompts cost double: at 200K prompt tokens or more, the higher rate applies to the whole request.
• Grok 4.7 Fast: exists, but only inside Cursor and Grok Build, not the public API.
• Aliases: a plain model name points to the latest stable version, -latest to the newest, and a dated name to a fixed release.

For SuperGrok plans and the full API rate card, see my Grok pricing guide.

Your first request

With xai-sdk

The xai-sdk builds a chat object. You append messages, then call sample() to get a reply.

import os
from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(model="grok-4.7")
chat.append(system("You are a helpful Python tutor. Keep answers short."))
chat.append(user("What is a Python decorator?"))

response = chat.sample()
print(response.content)

To continue the chat, append the response and the next user message, then sample again.

With the OpenAI SDK

response = client.responses.create(
    model="grok-4.7",
    input="What is a Python decorator?",
)
print(response.output_text)

Reasoning effort

Grok 4.7 always reasons before it answers. You choose how hard it thinks with four levels: low, medium, high (default) and xhigh.

response = client.responses.create(
    model="grok-4.7",
    reasoning={"effort": "low"},
    input="Give me three names for a hiking app.",
)

Higher effort is slower and uses more output tokens. Artificial Analysis measured about 81,000 output tokens per task at xhigh, against about 36,000 for Grok 4.6 at high, so pick xhigh only for hard problems.

Note: Reasoning cannot be turned off on Grok 4.7. For cheap, simple tasks, use low.

Streaming responses

Streaming prints the reply as it is written. With xai-sdk, loop over chat.stream():

chat = client.chat.create(model="grok-4.7")
chat.append(user("Write a short poem about Mars."))

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)
print()

Each loop gives you the growing response and the newest chunk. With the OpenAI SDK and Chat Completions, it looks like this:

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Write a short poem about Mars."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Function calling

Function calling lets Grok ask your code to run a function and use the result. Define the tool with a JSON schema, run what the model asks for, then send back the output.

import json
from xai_sdk.chat import user, tool, tool_result

def get_weather(city):
    return {"city": city, "temp_c": 19, "sky": "cloudy"}  # call a real API here

tools = [
    tool(
        name="get_weather",
        description="Get the current weather for a city.",
        parameters={
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    ),
]

chat = client.chat.create(model="grok-4.7", tools=tools)
chat.append(user("What's the weather in Dublin?"))
response = chat.sample()
chat.append(response)

for tc in response.tool_calls:
    args = json.loads(tc.function.arguments)
    chat.append(tool_result(json.dumps(get_weather(**args))))

print(chat.sample().content)

Here are the controls you can use:

• Parallel calls: on by default, so one reply can hold several calls. Handle them all before you sample again, or set parallel_tool_calls to false.
• tool_choice: auto (default), required, none, or a specific function name.
• OpenAI SDK route: use "type": "function" tools and return function_call_output items with the matching call_id.

Vision: sending images

Grok 4.7 accepts images with your text. Use the image() helper with a URL or a base64 data URL.

from xai_sdk.chat import user, image

chat = client.chat.create(model="grok-4.7")
chat.append(
    user(
        "What's in this image?",
        image(image_url="https://example.com/photo.jpg", detail="high"),
    )
)
print(chat.sample().content)

Image rules are simple:

• Formats: JPG/JPEG or PNG.
• Size: up to 20 MiB per image.
• Count: no limit on the number of images, in any order with text.

Live search: web and X

Grok’s big advantage is live data from the web and from X. Search now runs through server-side tools that Grok calls on its own, replacing the older Live Search parameters.

Web search

from xai_sdk.chat import user
from xai_sdk.tools import web_search

chat = client.chat.create(
    model="grok-4.7",
    tools=[web_search(allowed_domains=["docs.x.ai"])],
)
chat.append(user("What changed in the xAI API this month?"))
response = chat.sample()
print(response.content)
print(response.citations)

• allowed_domains / excluded_domains: up to 5 domains each, but not both in one request.
• enable_image_understanding: lets Grok look at images it finds while browsing.
• Cost: $5 per 1,000 web search calls, plus tokens.

X search

response = client.responses.create(   # OpenAI SDK client
    model="grok-4.7",
    input=[{"role": "user", "content": "What has SpaceX posted about Starship recently?"}],
    tools=[{"type": "x_search", "allowed_x_handles": ["SpaceX"]}],
)
print(response.output_text)

• Handles: allowed_x_handles or excluded_x_handles, up to 20, written without the @.
• Dates: from_date and to_date in YYYY-MM-DD format.
• Media: enable_image_understanding and enable_video_understanding, both off by default.
• Cost: $5 per 1,000 posts fetched and $10 per 1,000 user profiles fetched, plus tokens.

Prompt caching with x-grok-conv-id

Prompt caching works on all Grok language models. Cached input on Grok 4.7 costs $0.50 instead of $2 per million tokens.

The key is routing. xAI tells you to always set x-grok-conv-id (or prompt_cache_key in the Responses API) to a stable ID, so your requests reach the same server.

import uuid

conv_id = str(uuid.uuid4())   # reuse this for the whole conversation

response = client.chat.completions.create(
    model="grok-4.7",
    messages=history,
    extra_headers={"x-grok-conv-id": conv_id},
)
print(response.usage.prompt_tokens_details.cached_tokens)

To keep hit rates high, follow these rules:

• Never edit earlier messages: only append new ones, so the prefix stays the same.
• Use one ID per conversation: a UUID or your app’s session ID works well.
• Check the numbers: Chat Completions reports usage.prompt_tokens_details.cached_tokens, and Responses reports usage.input_tokens_details.cached_tokens.

Cache entries can be evicted at any time under load. My prompt caching guide compares how other providers handle it.

Rate limits and tiers

xAI sets limits per model, in requests per second and tokens per minute (TPM). Your tier rises automatically with total spend since January 1, 2026, and tiers never downgrade.

TPM counts prompt, completion, reasoning and cached tokens. You can see your current tier and per-model limits on the Models page in the xAI Console.

Errors and retries

xAI recommends exponential backoff, waiting 2 to the power of the attempt in seconds, for up to 5 retries:

import time
import openai

def ask(prompt, attempts=5):
    for i in range(attempts):
        try:
            return client.responses.create(model="grok-4.7", input=prompt)
        except (openai.RateLimitError, openai.APIConnectionError, openai.InternalServerError):
            time.sleep(2 ** i)
    raise RuntimeError("Gave up after retries")

Warning: With xai-sdk, a rate limit shows up as the gRPC status RESOURCE_EXHAUSTED, not as HTTP 429. Catch that status in your retry loop.

Troubleshooting common problems

Every call fails right after I create a key

Your team probably has no credits yet. Add credits in the xAI Console, then try again. Also check that you exported XAI_API_KEY in the same terminal.

“Model not found” errors

Use grok-4.7 with a dot. The hyphen form grok-4-7 is not a valid model ID. Grok 4.7 Fast is not on the public API.

My bill is higher than expected

• Long prompts: at 200K tokens or more, every token is billed at the higher rate.
• xhigh effort: it can use more than twice the output tokens of lower settings.
• Search tools: web and X search add per-call and per-post fees on top of tokens.

cached_tokens stays at 0

Set a stable x-grok-conv-id header and stop editing old messages. Keep system prompts and tool lists identical between calls.

logprobs come back empty

logprobs and top_logprobs are not supported on grok-4.20 and newer. They are ignored without an error. For a similar setup with another provider, see my DeepSeek API Python tutorial.

Frequently Asked Questions

Can I use the OpenAI Python SDK with Grok?

Yes. Create the client with your xAI key and base_url="https://api.x.ai/v1". Both the Responses API and Chat Completions work.

What is the latest Grok model on the API?

Grok 4.7 (grok-4.7), released September 21, 2026. It has a 500K token context window and accepts text and images.

How much does the Grok 4.7 API cost?

$2 per million input tokens, $0.50 cached and $6 output, for prompts under 200K tokens. At 200K or more, the rates double to $4, $1 and $12.

Does SuperGrok include API credits?

No. The API is billed separately with prepaid credits in the xAI Console. See my Grok pricing guide for plan details.

How do I get live search results from Grok?

Add the web_search or x_search tool to your request. Grok decides when to search and can return citations.

What does x-grok-conv-id do?

It routes all requests in one conversation to the same server, which raises your cache hit rate. Use a stable ID such as a UUID.

How do I raise my Grok rate limits?

Tiers rise automatically as your total spend grows, from Tier 0 at $0 to Tier 4 at $5,000. You can also request more in the console or contact xAI sales.

Sources

• xAI Docs: Quickstart
• xAI Docs: Models and pricing
• xAI Docs: Release notes
• xAI Docs: Function calling
• xAI Docs: Streaming
• xAI Docs: Image understanding
• xAI Docs: Web search tool
• xAI Docs: X search tool
• xAI Docs: Prompt caching best practices
• xAI Docs: Consumption and rate limits
• xAI Docs: Debugging errors
• Lindy: Grok 4.7 pricing and what changed
• EvoLink: Grok 4.7 release date and specs