Grok Config API | X Grok Eligibility and Models

GET grok/config returns the Grok settings of the X account behind your session: eligible, ineligible_reasons, free_access_enabled, the account's default mode and model, and model_options with each model's id, name and mode. It also returns the map from Grok Chat's mode values to X model ids. $0.0008 per call.

curl -X GET "https://example.com/grok/config"

{  "eligible": true,  "ineligible_reasons": [],  "free_access_enabled": false,  "default_mode": "Normal",  "default_model_option_id": "grok-4-auto",  "grok_version": "grok-4-auto",  "modes": {    "auto": "grok-4-auto",    "fast": "grok-3-latest",    "expert": "grok-4"  },  "model_options": [    {      "id": "grok-4-auto",      "name": "Auto",      "description": "Picks the model that suits the question.",      "mode": "MODEL_MODE_AUTO",      "is_enabled": true,      "is_analyze_enabled": false,      "is_enhance_enabled": false    },    {      "id": "grok-3-latest",      "name": "Fast",      "description": "Answers quickly.",      "mode": "MODEL_MODE_FAST",      "is_enabled": true,      "is_analyze_enabled": true,      "is_enhance_enabled": true    },    {      "id": "grok-4",      "name": "Expert",      "description": "Thinks for longer before answering.",      "mode": "MODEL_MODE_EXPERT",      "is_enabled": true,      "is_analyze_enabled": false,      "is_enhance_enabled": false    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

One $0.0008 read. The answer changes on the order of X plan changes, so cache it per account rather than calling it ahead of every chat request.

When to use

Call this once per account before your first Grok Chat request, and again if chat calls start failing for a reason you cannot see from the error alone. It tells you whether the account you are acting as can use Grok and which of auto, fast and expert it may pick. It sends no prompt and returns no answer; Grok Chat does that.

Notes

• [VERIFY] Response shape sourced from a live operator capture of X's GrokHome op (2026-08-16). Not executed live end-to-end through a customer key.
• PRICING IS PROVISIONAL. Neither grok slug is enumerated in billing/src/config/endpoint-costs.json, so computeCost() falls back to the standard read rate of $0.0008. See the same note on Grok Chat.
• Needs a session for the account you are asking about: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
• X's GrokHome op also returns a layout block of rotating suggested prompts for its own UI. It is dropped rather than passed through, so our response shape does not move when X redesigns that surface.

Related endpoints

• Grok Chat: Ask X's Grok a question and get the answer plus the pages it cited.
• Register Session: Register your auth_token and ct0 cookies once so every write and private read acts as your account, or pass them per call as x-auth-token / x-ct0 headers.
• User Login: Log in to X with a username and password (plus TOTP for 2FA) and store the resulting session against your API key, so authenticated-account reads and write tools then act as that account. A convenience alternative to bringing your own cookies via Register Session.

FAQ

Why does a read need my session? Everything else public does not.

Because the answer is about your account, not about Grok in general. X reports eligibility per account, based on plan, region and account age. Served off our shared pool this call would tell you what OUR account is allowed to do, which is a confidently wrong answer to the only question the endpoint exists to answer.

eligible came back false with no reasons. Am I ineligible?

Not necessarily. An empty ineligible_reasons next to eligible false means we could not read the account's Grok config, so we do not claim it has any state. When X genuinely refuses, it sends a reason string and you get it verbatim. Retry, and if it persists check the account can open x.com/i/grok in a browser.

What do I pass as mode on a chat call?

One of auto, fast, or expert. The modes object maps each to the X model id it selects: auto is grok-4-auto, fast is grok-3-latest, expert is grok-4. Grok Chat also accepts those raw ids, and anything it does not recognise falls back to auto.

Does calling this consume Grok quota?

No. It reads settings and sends no prompt, so it draws on your X account's Grok usage cap for nothing. It does cost one $0.0008 API call on our side, which is why caching it per account is worth doing.