--- title: "Grok Chat" method: POST path: "/grok/chat" tags: ["Grok"] --- # Grok Chat `POST /grok/chat` ## Request - Base URL: `https://api.twitterapis.com/twitter` - URL: `https://api.twitterapis.com/twitter/grok/chat` - Auth: HTTP bearer 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. ## Request body - object - `message` string: The prompt. A question, an instruction, or a bare post URL (https://x.com//status/), 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. - `messages` string: 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. - `mode` string: 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_id` string: 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_count` integer: 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. ## Response `200` Ask X's Grok a question and get the answer plus the pages it cited. - object - `ok` boolean: 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_id` string, 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_id` string: 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_id` string: The id of the turn YOU just sent (X's userChatItemId). Its counterpart to response_id when you replay history. - `answer` string: Grok's answer as one complete string. Reasoning and tool chatter are stripped out; this is the reply a person would read. - `citations` object[]: 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_count` integer: Length of citations, after de-duplication. Convenient for the common case of checking whether a domain appeared at all. - `tool_calls` object[]: 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_model` string: The model id we asked X for, derived from your mode: grok-4-auto, grok-3-latest, or grok-4. - `model` string: 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. - `mode` string: The mode this call ran in: auto, fast, or expert. Echoed back so an unrecognised mode value is visible rather than silent. ## Other responses - `400`: Bad request - `401`: Unauthorized - `402`: Insufficient credits - `403`: Forbidden - `404`: Not found - `429`: Rate limited - `5XX`: Server error --- [API](https://skmtc.dev/twitterapis/apis/twitterapis-api.md) · [All operations](https://skmtc.dev/twitterapis/apis/twitterapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/twitterapis/apis/twitterapis-api/revisions/a33ce0fedb3c?raw)