Grok

Grok Chat

Send a prompt to X's in-app Grok as the account behind your session and get back one complete JSON document: the answer text, the web pages Grok cited while writing it, and the searches it ran to find them. Grok reads X in real time, so it answers about posts and accounts a general-purpose model has never seen. Send a bare post URL as the message and you get a structured summary of that post instead, including what Grok reads out of its attached images. Billed at $0.0040 per answer. Cost: $0.0040 per call.

post/grok/chat

Request

  • Base URL: https://api.twitterapis.com/twitter
  • URL: https://api.twitterapis.com/twitter/grok/chat
  • Auth: HTTP bearer

Request body

messagestring

The prompt. A question, an instruction, or a bare post URL (https://x.com/<user>/status/<id>), which returns a summary of that post. Required unless you send messages[] whose last entry is a user turn. Maximum 20,000 characters; longer prompts are rejected with 400 before any Grok call is made, so an over-length prompt never costs you anything.

messagesstring

JSON array of prior turns, oldest first, sent in the request body. Each entry takes either { role: "user" | "assistant", content } or X's own { sender: 1 | 2, message }, where 1 is you and 2 is Grok, plus the optional response_id and parent_response_id we returned on earlier replies. Anything not explicitly marked as Grok is treated as a user turn. If you omit message, the last entry must be a user turn and becomes the prompt. Maximum 100 prior turns.

modestring

auto, fast, or expert. auto lets X pick the model, fast is grok-3-latest, expert is grok-4 and thinks for longer. The raw model ids grok-3-latest and grok-4 are accepted as aliases. Anything unrecognised falls back to auto, which is also the default.

conversation_idstring

Continue an existing conversation, using the conversation_id from an earlier reply. Omit it and we open a fresh conversation for you and return its id.

image_countinteger

How many images Grok may generate if the prompt calls for it. Clamped to 0 through 4; the default is 4, which is X's own. Set it to 0 for a text-only answer.

Example request

{
  "message": "What are people on X saying about the WWDC keynote today?",
  "messages": "[{\"role\":\"user\",\"content\":\"Who won the game?\"},{\"role\":\"assistant\",\"content\":\"The Celtics, 112-108.\"}]",
  "mode": "auto",
  "conversation_id": "2088999211077345534"
}

Response

Ask X's Grok a question and get the answer plus the pages it cited.

okboolean

True when Grok returned answer text. A call that produced no readable answer does not reach you as ok: false, it returns 422 and is not billed.

conversation_idstring nullable

The conversation this turn belongs to, whether you supplied it or we opened it. Pass it back on the next call to continue. Null only if X returned no id.

response_idstring

The id of GROK's turn (X's agentChatItemId). Pass it back as response_id on that turn inside messages[] to thread the next request exactly.

user_response_idstring

The id of the turn YOU just sent (X's userChatItemId). Its counterpart to response_id when you replay history.

answerstring

Grok's answer as one complete string. Reasoning and tool chatter are stripped out; this is the reply a person would read.

citationsobject[]

The pages Grok read while answering, each { url, domain, title, snippet }. domain is derived from url on our side; X does not send it. title is NOT always present and comes back null when X omits it, so do not filter on it. One answer can cite results from several searches: they are merged in the order they arrived and de-duplicated by url, so you get every distinct source once.

citation_countinteger

Length of citations, after de-duplication. Convenient for the common case of checking whether a domain appeared at all.

tool_callsobject[]

What Grok actually ran to answer, each { id, tool, args }. The observed tool is web_search, whose args carry the query string and the number of results asked for. This is the search Grok chose, not the prompt you sent.

requested_modelstring

The model id we asked X for, derived from your mode: grok-4-auto, grok-3-latest, or grok-4.

modelstring

The model that ACTUALLY answered. auto resolves on X's side, so asking for grok-4-auto commonly comes back as grok-4. Read this one when you care which model produced the text.

modestring

The mode this call ran in: auto, fast, or expert. Echoed back so an unrecognised mode value is visible rather than silent.

Changes

No recorded changes to this operation across all 1 revision of this API.