xAI SDK AsyncClient

Why switch to async

When you query the xAI API synchronously, each call blocks your program’s execution until the response arrives. For a reasoning model like grok-4.5, a single request can take several tens of seconds. If you need to process 100 requests, the total wait time becomes prohibitive.

Async mode solves this problem. Instead of waiting for each response, your program launches the request and continues execution. You retrieve the result later, when it is available. This approach lets you process multiple requests in parallel and fully utilize your bandwidth to the API.

Initialize the AsyncClient

The xAI SDK provides an AsyncClient class dedicated to async calls. Initialization is similar to the sync client, with a timeout parameter you must always configure:

import os
from xai_sdk import AsyncClient
from xai_sdk.chat import user

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    timeout=3600,
)

timeout=3600 equals one hour. This value might seem high, but it is necessary for reasoning models that perform extended reasoning before responding. A timeout that is too short causes connection drop errors on complex requests.

Send an async request

Once you initialize the client, you send requests using Python’s await syntax:

import asyncio

async def ask_grok(question: str) -> str:
    chat = client.chat.create(
        model="grok-4.20-0309-reasoning",
        max_tokens=500
    )
    chat.append(user(question))
    response = await chat.sample()
    return response.text

# Entry point
result = asyncio.run(ask_grok("Explain the algorithmic complexity of quicksort"))
print(result)

The ask_grok function uses async def, making it a coroutine. The await chat.sample() call suspends this coroutine until the response arrives, without blocking other potential tasks.

Difference from the sync client

The sync client blocks the current thread for the entire duration of the request. The async client frees the thread to execute other coroutines. This distinction doesn’t matter if you send only one request, but it becomes critical when you process multiple requests in parallel.

# Sync: each call waits for the response
for question in questions:
    response = client.chat.completions.create(...)  # blocking
    process(response)

# Async: calls run in parallel
async def main():
    tasks = [ask_grok(q) for q in questions]
    responses = await asyncio.gather(*tasks)  # parallel
    for r in responses:
        process(r)

In the sync example, if each request takes 10 seconds and you have 20, the total time is 200 seconds. In async mode with a semaphore of 5 (which you will discover in later lessons), the time drops to about 40 seconds.

Key takeaways

• The xAI SDK AsyncClient lets you send requests without blocking execution
• The timeout=3600 parameter is essential for reasoning models
• The xai-sdk requires Python 3.10 or later (version 1.21.0 as of November 2, 2026, per PyPI)
• The real benefit appears when processing multiple requests in parallel
• asyncio.run() serves as the entry point to execute a coroutine from sync code