GET

/v1/schemas/grok/chat/v1%2Fchat%2Fcompletions

kind inputactivity chathash aef83794…extracted Oct 28, 2026version currentsource upstream spec ↗

Request body

29 properties · 0 required · 20 $defs
propertytypedescriptionconstraints
deferredanyIf set to `true`, the request returns a `request_id`. You can then get the deferred response by GET `/v1/chat/deferred-completion/{request_id}`.default: false
frequency_penaltyany(Not supported by reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.-2 ≤ n ≤ 2 · format: float · default: 0
guidelinesanyPer-category instructions for model output. See [`Guideline`]. Omitted requests leave this unset. A request whose guidelines cannot be applied, for example on a multi-agent model or with `stop`, fails with 400.
logit_biasany(Unsupported) A JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per m…
logprobsanyWhether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. Not supported by models `grok-4.20` and newer; the field will be silently ignored if set.default: false
max_completion_tokensanyAn upper bound for the number of tokens that can be generated for a completion, only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls). Defaults to 128,000 when unset; set a larger value to allow longer gener…format: int32
max_tokensany\[DEPRECATED\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`.format: int32
messagesMessage[]A list of messages that make up the chat conversation. Different models support different message types, such as image and text.
modelstringModel name for the model to use. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.
nanyHow many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep n as 1 to minimize costs.n ≥ 1 · format: int32 · default: 1
parallel_tool_callsanyIf set to false, the model can perform maximum one tool call.default: true
presence_penaltyany(Not supported by `grok-3` and reasoning models) Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.-2 ≤ n ≤ 2 · format: float · default: 0
prompt_cache_keyanyA stable cache key for best-effort sticky routing / prompt-cache hits across requests sharing a prompt prefix. Plumbed to `x-grok-conv-id`, same as on `/v1/responses`.
reasoning_effortanyConstrains how hard a reasoning model thinks before responding. Higher efforts use more reasoning tokens for deeper thinking. The supported values and the default depend on the model.
response_formatobject | object | objectAn object specifying the format that the model must output. Specify `{ "type": "json_object" }` for JSON output, or `{ "type": "json_schema", "json_schema": {...} }` for structured outputs. If `{ \"type\": \"text\" }`, the model will return a text response.nullable
safety_identifieranySupplied by the API client to identify the end user behind this request. A stable string that uniquely identifies each of your users; hash your internal user id or username rather than sending an email or name. Stored with the request metadata so a usage-polic…
search_parametersSearchParametersDeprecated: live search has been removed, and requests that set this field fail. Use the Agent Tools API instead: <https://docs.x.ai/developers/tools/overview>.nullable
seedanyIf specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` respons…format: int32
service_tierenumProcessing tier. `"fast"` and `"priority"` are interchangeable: on models with a fast deployment both use it and its rates; otherwise both mean higher scheduling priority at a higher price. Valid: `"auto"`, `"priority"`, `"fast"`.default | priority | fast · nullable
stopany(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens.
streamanyIf set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]` message.default: false
stream_optionsStreamOptionsOptions for streaming response. Only set this when you set `stream: true`.nullable
temperatureanyWhat sampling temperature to use, between 0 and 2. Values above 1 are sampled at 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.0 ≤ n ≤ 2 · format: float · default: 1
tool_choicestring | objectControls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one …nullable
toolsanyA list of tools the model may call in JSON-schema. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 1000 functions are supported.items ≤ 1000
top_logprobsanyAn integer between 0 and 8 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used. Not supported by models `grok-4.20` and newer; the field w…0 ≤ n ≤ 8 · format: int32
top_panyAn alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally reco…0 < n ≤ 1 · format: float · default: 0.95
useranyA unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
web_search_optionsWebSearchOptionsDeprecated: live search has been removed, and requests that set this field fail. Use the Agent Tools API instead: <https://docs.x.ai/developers/tools/overview>.nullable

Validate a payload

before you spend tokens
shell
$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"grok","endpointId":"v1/chat/completions","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}