GET

/v1/schemas/grok/chat/v1/chat/completions

Accept:

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

field	recorded source
schema	Source linked above. upstream-spec Source trace `ba7fa0aee6b67a25f648797321f9ecfd0a4869f577325942ac611941b0501441` { "fetchedAt": 1793164224, "extractorVersion": "1", "verifiedAt": null }

Request body

29 properties · 0 required · 20 $defs

property	type	description	constraints
deferred	any	If 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_penalty	any	(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
guidelines	any	Per-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_bias	any	(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…
logprobs	any	Whether 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_tokens	any	An 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_tokens	any	\[DEPRECATED\] The maximum number of tokens that can be generated in the chat completion. Deprecated in favor of `max_completion_tokens`.	format: int32
messages	Message[]	A list of messages that make up the chat conversation. Different models support different message types, such as image and text.
model	string	Model name for the model to use. Obtainable from <https://console.x.ai/team/default/models> or <https://docs.x.ai/docs/models>.
n	any	How 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_calls	any	If set to false, the model can perform maximum one tool call.	default: true
presence_penalty	any	(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_key	any	A 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_effort	any	Constrains 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_format	object \| object \| object	An 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_identifier	any	Supplied 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_parameters	SearchParameters	Deprecated: 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
seed	any	If 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_tier	enum	Processing 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
stop	any	(Not supported by reasoning models) Up to 4 sequences where the API will stop generating further tokens.
stream	any	If 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_options	StreamOptions	Options for streaming response. Only set this when you set `stream: true`.	nullable
temperature	any	What 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_choice	string \| object	Controls 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
tools	any	A 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_logprobs	any	An 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_p	any	An 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
user	any	A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.
web_search_options	WebSearchOptions	Deprecated: 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

Types

20 $defs

Contentstring | ContentPart[]

Content of each chat message.

ContentPartobject

file	FileRef	File reference for file attachments (OpenAI-compatible nesting).	nullable
image_url	ImageUrl	Image prompt. An object `{url, detail}` on chat completions, or a string URL on Responses `input_image`.	nullable
text	any	Text prompt.
type*	string	The type of the content part. Can be `text`, `image_url`, `text_file` or `file`. `input_text` and `input_image` are accepted so a tool result can use the same content items as `/v1/responses` `function_call_output`.

FileRefobject

file_id	any	The file ID from the Files API.
url	any	Public URL for a file attachment.

Functionobject

arguments*	string
name*	string

FunctionChoiceobject

Function name.

name*

string

FunctionDefinitionobject

Definition of the tool call made available to the model.

defer_loading	any	When true, the definition is hidden from the model's prompt but stays callable, loaded via a `tool_search` step (`/v1/responses` only).
description	any	A description of the function to indicate to the model when to call it.
name*	string	The name of the function. If the model calls the function, this name is used in the response.
parameters*	any	A JSON schema describing the function parameters. The model _should_ follow the schema, however, this is not enforced at the moment.
strict	any	Not supported. Only maintained for compatibility reasons.

Guidelineobject

One entry in [`ChatRequest::guidelines`] and [`ModelRequest::guidelines`].

behavior*	enum	How the model should handle a [`GuidelineCategory`].	decline \| allow
category*	enum	Content category a guideline applies to.	nsfw \| violence \| profanity \| cyber
type*	string	Discriminator. Must be `policy`.

GuidelineBehaviorenum

How the model should handle a [`GuidelineCategory`].

decline | allow

GuidelineCategoryenum

Content category a guideline applies to.

nsfw | violence | profanity | cyber

ImageUrlobject

Image input for generation and editing requests. Accepts a public URL, a base64-encoded data URL, or a file_id from the xAI Files API.

file_id	any	File ID from the xAI Files API. Mutually exclusive with `url`. The file must be an image (JPEG, PNG, or WebP) and fully uploaded.
url	string	Public URL or base64-encoded data URL of the image (JPEG, PNG, or WebP). Also accepts `image_url` for compatibility. Required when `file_id` is not set.

Messageobject | object | object | …

Chat message objects.

ResponseFormatobject | object | object

Response format parameter for structured outputs.

SearchParametersobject

Parameters to control realtime data.

from_date	any	Date from which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.	format: date
max_search_results	any	Maximum number of search results to use.	1 ≤ n ≤ 30 · format: int32 · default: 15
mode	any	Choose the mode to query realtime data: * `off`: no search performed and no external will be considered. * `on` (default): the model will search in every sources for relevant data. * `auto`: the model choose whether to search data or not and where to search th…	default: "auto"
return_citations	any	Whether to return citations in the response or not.	default: true
sources	any	List of sources to search in. If no sources specified, the model will look over the web and X by default.
to_date	any	Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.	format: date

SearchSourceobject | object | object | …

ServiceTierenum

Processing tier for a request. `Fast` and `Priority` are interchangeable: the model's fast deployment and its rates where configured, else higher scheduling priority at a higher price.

default | priority | fast

StreamOptionsobject

Options available when using streaming response.

include_usage*

boolean

Set an additional chunk to be streamed before the `data: [DONE]` message. The other chunks will return `null` in `usage` field.

Toolobject | object

Definition of one tool that the model can call.

ToolCallobject

function*	Function	Function to call for the tool call.
id*	string	A unique ID of the tool call generated by xAI. After performing tool call's function, user provides this ID with tool call's result in the subsequent request to xAI. xAI can then match the tool call result sent with tool call request.
index	any	Index of the tool call.	format: int32
type	any	Type of tool call, should be `"function"` or `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"`

ToolChoicestring | object

Parameter to control how model chooses the tools.

WebSearchOptionsobject

filters	any	Only included for compatibility.
search_context_size	any	This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`.	default: "medium"
user_location	any	Only included for compatibility.

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", …}]}