Search X posts with the Grok API

Pass x_search on POST https://api.x.ai/v1/responses. xAI runs keyword, semantic, user, and thread search on X and returns the answer plus citations. You need a key and credits at console.x.ai.

Minimal call

export XAI_API_KEY="your_api_key"

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.6",
  "input": [
    {
      "role": "user",
      "content": "What are people saying about xAI on X?"
    }
  ],
  "tools": [
    { "type": "x_search" }
  ]
}'

Python with the official SDK:

import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-4.6", tools=[x_search()])
chat.append(user("What are people saying about xAI on X?"))
for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="", flush=True)
print("\nCitations:", response.citations)

Narrow the search

• allowed_x_handles / excluded_x_handles — max 20 each. Do not set both on one request.
• from_date / to_date — ISO8601 (YYYY-MM-DD). The SDK also accepts datetime objects.
• enable_image_understanding — analyze images in posts the tool finds.
• enable_video_understanding — analyze videos in those posts.

Citations arrive on the response. See the Citations page for how to read them.

Pitfalls

• allowed_x_handles and excluded_x_handles cannot share a request.
• enable_video_understanding is on X search only.
• Open the cited posts before you act on a number.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.