Most coverage of xAI is really coverage of two different things wearing one name. One is Colossus, the physical compute cluster xAI operates across sites in Memphis, Tennessee and neighbouring Southaven, Mississippi — by mid-2026 a multi-building installation on the order of a gigawatt of IT power, built to train Grok models and, at various points, to lend capacity to related Musk ventures [15]. The other is the Grok API: a REST endpoint at https://api.x.ai/v1 that a developer authenticates against, sends JSON to, and gets billed for by the token. These two things share a press cycle but almost nothing else. A gigawatt of training compute tells you nothing about what max_completion_tokens defaults to, what happens when you send your four-hundredth request this second, or whether the model you pinned in January will still answer to that name in June. This article stays entirely on the second side of that line. It is a working guide to what xAI’s own developer documentation says about building a production integration against Grok, sourced exclusively from that documentation and, where a genuine point of contrast is useful, from the equivalent published documentation of two APIs a developer is likely to already know.
That restriction is deliberate, and it rules some things out explicitly. xAI has not published a parameter count for any Grok model in its API documentation, its model cards, or its release posts — the models page describes grok-4.6 in capability terms, as “the most intelligent and fastest model” xAI has shipped, without a parameter figure attached [1] [12]. Specific parameter numbers for various Grok models circulate in secondary reporting and in posts from company accounts and individuals, and they disagree with each other by factors of two or more depending on the source and the week. None of that is a primary disclosure, and none of it appears anywhere below. Where this article states a number, it is a number xAI has put in a document meant for developers to build against, not a rumor meant for a headline.
Getting an authenticated request out the door
The Grok API is a bearer-token REST API, and xAI’s own quickstart treats the credential as the whole of the authentication story: create an account, generate a key on the API Keys page, and either export it as XAI_API_KEY or drop it into a .env file before your first call [9]. Every subsequent request carries that key in an Authorization: Bearer $XAI_API_KEY header [2]. There is no separate OAuth flow, no per-request signing, and no session token layered on top — the credential presented on the call is the entire proof of identity, request after request. That single-header simplicity is also the entire attack surface: a leaked key is a fully authorized key until it is rotated, since nothing else stands behind it.
The endpoint surface itself has two generations living side by side. POST /v1/chat/completions is the familiar shape — a messages array in, a completion out — and it is also the shape OpenAI’s own SDK expects, which xAI leans on directly: the documented migration path for an existing OpenAI integration is to keep the client library and change two arguments, pointing base_url at https://api.x.ai/v1 and swapping in an xAI key [8]. The newer POST /v1/responses endpoint adds state: a store flag (true by default) controls whether xAI retains the exchange server-side, and a returned response ID can be passed back as previous_response_id on the next call instead of resending the full conversation history, with stored responses kept for thirty days before removal [8] [2]. A related POST /v1/responses/compact endpoint compresses an accumulating history into what the documentation calls a shorter canonical window, which matters once a long-running agent’s context starts to press against a model’s limit [2]. One documented operational detail is easy to miss and expensive to miss in production: xAI’s own compatibility example sets an explicit long client timeout — httpx.Timeout(3600.0), a full hour — specifically for reasoning models, because a request that thinks for a long time before answering will simply hang past whatever default timeout an OpenAI-client integration shipped with [8].
The model catalogue as xAI actually documents it
xAI’s models page lists a small, named set of production models rather than a single “Grok” endpoint, and each one carries its own context limit and its own two-tier price [1]. As documented on 15 August 2026: grok-4.6, released 12 August 2026 and priced from launch at two dollars per million input tokens and six dollars per million output tokens [12], carries a 500,000-token context window; grok-4.5 shares that same 500K window at the same base input and output price but a lower cached-token rate; grok-4.3 and the dated grok-4.20 variants (a reasoning build, a non-reasoning build, and a multi-agent build) extend to a 1,000,000-token window at roughly half grok-4.6’s per-token price; and grok-build-0.1, positioned for coding work, sits at a 256,000-token window and the lowest published price of the set [1]. On the multi-agent variant specifically, the documentation states that its reasoning-effort setting controls the number of agents spawned rather than the depth of a single chain of thought — a genuinely different control from what the same parameter name does on the standard models [7].
The pricing structure has a feature worth building a mental model around before it costs you money in production: it is not a marginal rate that blends smoothly as a request grows, it is a cliff. Every model’s documented price list carries two tiers — one for requests under 200,000 tokens, and a materially higher one, roughly double across the board, once a request reaches that threshold — and the higher rate applies to the entire request, not just the tokens past the line [1]. Written as a cost function of input tokens
For grok-4.6 that means a 199,999-token prompt is billed at two dollars per million input tokens, and a 200,001-token prompt — one token longer — is billed at four dollars per million input tokens and twelve dollars per million output tokens for the whole request, not a blended rate [1]. A retrieval-augmented pipeline that occasionally pads a prompt with one extra chunk of context can cross that line without any change in what the request is actually asking for, and the bill for that request roughly doubles. This is a discontinuity, not a slope, and it is the kind of detail a cost estimate built from a single “price per million tokens” figure will get wrong in exactly the requests that matter most, because long-context requests are disproportionately the expensive ones to mis-price.
What the documentation says is actually different: Live Search and X Search
The most substantive documented divergence from other frontier APIs is a pair of built-in tools. xAI’s Web Search tool lets Grok “search the web in real-time and browse web pages to find information,” configurable with allowed_domains or excluded_domains (five each, mutually exclusive) and optional image understanding and image search [5]. That much has close analogues elsewhere: OpenAI documents a web_search tool that gives its models “access to up-to-date information from the internet and provide answers with sourced citations,” including image results and domain filtering [13], and Anthropic documents a web_search tool for Claude with the same general shape — real-time web content, cited sources, allowed_domains or blocked_domains, and, in later tool versions, a user_location parameter for localizing results [14]. On general web search, the three vendors’ documentation describes broadly comparable capability.
The X Search tool is where xAI documents something the other two do not. It is a separate, named tool from web search, and its documented scope is specifically the X platform: “keyword search, semantic search, user search, and thread fetch on X,” filterable by up to twenty allowed or excluded handles and by an ISO 8601 from_date/to_date range, with optional understanding of images and video attached to posts [6]. Neither OpenAI’s nor Anthropic’s published tool documentation describes an equivalent platform-specific social-search tool; OpenAI’s web search guide makes no mention of X, Twitter, or any social platform as a distinct data source, and its only social-adjacent detail is that a developer can choose to block sites like Reddit from general web results [13], while Anthropic’s web search documentation is similarly silent on any platform-specific integration [14]. That silence in two competitors’ documentation is itself informative: it means a request for “what is being said about this on X right now, from these accounts, in this date range” is something Grok’s documented tool surface can express directly as a single tool call with typed parameters, where the same request against an API without a comparable tool would have to be built by hand — scraping, a third-party search provider, or a general web search that may or may not surface X content at all. That is a real, documented, practically useful difference in capability shape. It is not a claim about which model answers better; it is a claim about what one tool, specifically, is documented to do that the equivalent tool in two other vendors’ documentation is not documented to do.
Reasoning effort and tool calls: parameters that change what you’re billed for
Grok’s reasoning models expose a reasoning_effort parameter with four documented values — low, medium, high, and, on grok-4.6 and later only, xhigh (requesting it on an earlier model is treated as high) — and the documentation is explicit that if the parameter is omitted it defaults to high, and that reasoning itself cannot be turned off on a reasoning model [7]. That has a direct billing consequence worth stating plainly: reasoning tokens are billed as part of total consumption alongside prompt and completion tokens, so an unset reasoning_effort is not a neutral default, it is a decision to pay for the model’s most expensive thinking mode on every call [7]. The documentation also lists a hard incompatibility: presencePenalty, frequencyPenalty, and stop sequences cannot be sent to a reasoning model, and a request that includes them returns an error rather than being silently ignored [7] — a detail that will surface immediately if a codebase ports sampling parameters over from a non-reasoning integration without checking which model they are now pointed at.
Tool calling has its own limits, and they differ depending on which endpoint is in use. A tool definition needs a name, a description, and a JSON schema for its parameters, with parallel tool calls enabled by default so the model can request several in one response [11]. The chat completions endpoint documents a cap of 128 functions per request, while the newer responses endpoint documents a higher cap of 200 tools per request [2] [11] — a small but real inconsistency between the two API generations that is worth checking against whichever endpoint a given integration actually calls, rather than assuming the number quoted for one applies to the other. tool_choice accepts auto, required, none, or a reference to one specific function, giving explicit control over whether the model is allowed to skip tool use entirely [11].
Rate limits and error handling in practice
Rate limits are assigned by tier, and the tier is set by cumulative spend since 1 January 2026: Tier 0 at zero dollars, Tier 1 at fifty, Tier 2 at two hundred fifty, Tier 3 at one thousand, Tier 4 at five thousand, and an Enterprise tier by request — and the documentation states plainly that a tier, once reached, does not downgrade [3]. Each model carries its own requests-per-second and tokens-per-minute ceiling per tier; for grok-4.6 specifically, Tier 0 allows 150 RPS and 50 million TPM, rising to 500 RPS and 100 million TPM at Tier 4, while the multi-agent variant’s ceiling is far lower — 9 RPS and 2.5 million TPM at Tier 0 — reflecting how much more each of its calls actually costs to serve [3]. Every token counted toward that ceiling includes prompt tokens, completion tokens, reasoning tokens, and cached tokens together, not completion tokens alone [3].
What happens at the ceiling is documented as a flat, immediate stop rather than a graceful degradation: exceeding a limit returns HTTP 429 Too Many Requests, and the documented remedy is to reduce request rate, implement exponential backoff, or raise the account’s tier [3]. The broader debugging guide lists the rest of the documented error surface plainly — 400, 401, 403, 404, 405, 415, 422, and 429 among 4xx responses, plus 202 Accepted as the expected pending state for a deferred completion request — and states that most errors carry a self-explanatory message, with a 401 specifically resolved by supplying the Authorization: Bearer header correctly [4]. What the documentation does not provide is a formal structured error-body schema beyond that; a production integration has to treat the status code as the primary signal and the message text as advisory, and the guide points developers toward status.x.ai for service-level disruptions and toward emailing a request/response pair to xAI’s support address when a response looks wrong rather than merely rate-limited [4].
Model versioning: what “the same model name” actually guarantees
xAI’s own migration documentation gives a concrete, dated example of what happens when a model is retired, and it is worth treating as the reference case for how the platform behaves rather than assuming a hypothetical. Effective 15 May 2026 at noon Pacific time, eight model slugs were retired: grok-4-1-fast-reasoning, grok-4-1-fast-non-reasoning, grok-4-fast-reasoning, grok-4-fast-non-reasoning, grok-4-0709, grok-code-fast-1, grok-3, and grok-imagine-image-pro [10]. After that deadline, the documentation states, requests sent to any of those retired slugs do not fail — they are automatically redirected: the reasoning slugs to grok-4.3 at low reasoning effort, the non-reasoning slugs to grok-4.3 at none reasoning effort, and the retired image model to grok-imagine-image-quality [10]. Crucially, the redirected traffic is billed at the successor model’s price, not the retired model’s price — continuing to call grok-3 after the deadline gets you grok-4.3 output at grok-4.3’s rate, whatever your code still believes it asked for [10].
That precedent is the whole argument for pinning a model identifier explicitly and treating any convenience alias as something someone else controls the routing of. A team that had hard-coded grok-3 because it was “the stable one” did not get an outage on 15 May 2026; it got a silently different model, at a silently different reasoning setting, at a silently different price, with no code change on their end and, per the documentation, no requirement that they had opted in. The lesson generalizes past this one date: xAI’s own guidance to a team using a still-supported but ageing model is to check whether prompts and parameters still perform as expected on the recommended successor before migrating deliberately, rather than waiting to be redirected involuntarily [10].
What this guide deliberately leaves out
None of the above requires knowing anything about Colossus, and nothing in xAI’s API documentation mentions it — the models page describes context windows and prices, not hardware, and the same is true of the rate-limit, error, and tool-reference pages cited throughout this piece [1] [3] [4]. Colossus is a real, separately documented thing: a compute cluster across sites in Memphis, Tennessee and Southaven, Mississippi, built to train Grok models, reaching on the order of a gigawatt of combined IT power by mid-2026 according to independent tracking of the build [15]. It is not a Grok model, and scale claims about the cluster are not, by themselves, claims about what any specific Grok model contains or how it will perform on your workload. The economics, energy draw, and physical build-out of that cluster are a different, substantial subject, and this publication treats them separately rather than folding them into a document about calling an API. The same discipline applies to parameter counts: this article states none, because xAI has published none in the documentation a builder actually integrates against, and a number’s frequent repetition in secondary coverage is not the same thing as its appearance in a primary disclosure.
A short checklist before shipping
Four things follow directly from the documentation above and are worth treating as a pre-launch checklist rather than trivia. Pin an exact model identifier rather than relying on convenience, and re-test deliberately against xAI’s documented successor before a retirement deadline forces the substitution [10]. Set reasoning_effort explicitly on every reasoning-model call rather than accepting the high default silently, since that default is also the most expensive one available and the parameter cannot be unset back to “no reasoning” [7]. Watch prompt length against the 200,000-token pricing boundary specifically, not just against the context window, since crossing it changes the price of the entire request rather than the marginal tokens [1]. And reach for the X Search tool, not the general web search tool, when a request is actually about content on X — it is the one documented capability among the three vendors compared here with no equivalent in the other two’s published tool references, and asking a general web search tool to do a platform-specific job it was never documented to do is a common, avoidable source of a request that technically succeeds and practically disappoints [6] [13] [14].
