GET

/v1/schemas/grok/chat/v1/responses?kind=output

Accept:

kind outputactivity chathash b77de6bb…extracted Oct 29, 2026version currentsource upstream spec ↗

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

Response body

32 properties · 18 required · 42 $defs

property	type	description	constraints
background*	boolean	OpenResponses compatibility fields. Not used at the moment. Just for OpenResponses compatibility. Whether to process the response asynchronously in the background.	default: false
created_at*	integer	The Unix timestamp (in seconds) for the response creation time.	format: int64
frequency_penalty*	number	(NOT SUPPORTED in Responses API) 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.	format: float
id*	string	Unique ID of the response.
metadata*	any	Only included for compatibility.
model*	string	Model name used to generate the response.
object*	string	The object type of this resource. Always set to `response`.
output*	ModelOutput[]	The response generated by the model.
parallel_tool_calls*	boolean	Whether to allow the model to run parallel tool calls.
presence_penalty*	number	(NOT SUPPORTED in Responses API) 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.	format: float
service_tier*	enum	Specifies the processing tier used for serving the request.	default \| priority \| fast
status*	string	Status of the response. One of `completed`, `in_progress` or `incomplete`.
store*	boolean	Whether to store the input message(s) and model response for later retrieval.	default: true
text*	ModelResponseConfiguration	Settings for customizing a text response from the model.
tool_choice*	string \| object	Controls which (if any) tool is called by the model. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function…
tools*	ModelTool[]	A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 1000 tools are supported.	items ≤ 1000
top_logprobs*	integer	An integer between 0 and 8 specifying the number of most likely tokens to return at each token position.	format: int32
truncation*	string	The truncation strategy to use for the model response.	default: "disabled"
completed_at	any	The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed.	format: int64
error	any	An error object returned when the model fails to generate a response.
incomplete_details	object \| object \| object \| …	Details about why the response is incomplete.	nullable
instructions	any	A system (or developer) message inserted into the model's context.
max_output_tokens	any	Max number of tokens that can be generated in a response. Only applies to visible output tokens (i.e. does not apply to tokens used for reasoning or function calls).	format: int32
max_tool_calls	any	The maximum number of tool calls allowed for this response.	format: int32
previous_response_id	any	The ID of the previous response from the model.
prompt_cache_key	any	The cache key used for the prompt for routing to the correct engine.
reasoning	ReasoningConfiguration	Reasoning configuration. Only for reasoning models.	nullable
safety_identifier	any	A stable identifier used to help detect users of your application that may be violating xAI's usage policies.
temperature	any	Sampling temperature echoed from the request, or the model's default when the request omits it. Between 0 and 2. Sampling uses at most 1, so a sent value above 1 is echoed here and sampled as 1.	0 ≤ n ≤ 2 · format: float · default: 1
top_p	any	Nucleus sampling `top_p` echoed from the request, or the model's default when the request omits it. Sampling uses at most the model's default `top_p`, so a higher sent value is echoed here and sampled as that default.	0 < n ≤ 1 · format: float · default: 1
usage	ModelUsage	Token usage information.	nullable
user	any	A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

Types

42 $defs

Annotationobject

end_index	any	The end index of the annotation.	format: int32
start_index	any	The summary of the annotation.	format: int32
title	any	The title of the annotation.
type*	string	The type of the annotation. Only supported type currently is `url_citation`.
url*	string	The URL of the web resource.

CodeInterpreterCallobject

The output of a code interpreter tool call.

code	string	The code of the code interpreter tool call.
id	string	The unique ID of the code interpreter tool call.
outputs*	CodeInterpreterOutput[]	The outputs of the code interpreter tool call.
status	string	The status of the code interpreter tool call.
type*	string	The type of the code interpreter tool call. Always `code_interpreter_call`.

CodeInterpreterOutputobject | object

ContextDetailsobject

Token counts for the latest context window seen by the model.

input_tokens*	integer	Prompt tokens in the latest context (sourced from `SamplingUsage.context_prompt_tokens`).	format: int32
output_tokens*	integer	Completion + reasoning tokens in the latest context (sourced from `SamplingUsage.context_output_tokens`).	format: int32

CustomToolCallobject

The output of a custom tool call.

call_id*	string	The unique ID of the function tool call generated by the model.
id*	string	The status of the custom tool call.
input	string	The unique ID of the custom tool call,
name*	string	An identifier used to map this custom tool call to a tool call output.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The input for the custom tool call generated by the model.

FileSearchCallobject

The output of a web search tool call.

id	string	The unique ID of the file search tool call.
queries*	string[]	The queries used to search for files.
results*	FileSearchResult[]	The results of the file search tool call.
status	string	The status of the file search tool call.
type*	string	The type of the file search tool call. Always `file_search_call`.

FileSearchResultobject

file_id*	string	The file ID of the file search result.
filename*	string	The filename of the file search result.
score	number	The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent.	format: double
text*	string	The text of the file search result.

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.

FunctionToolCallobject

A tool call to run a function.

arguments*	string	The arguments to pass to the function, as a JSON string.
call_id*	string	The unique ID of the function tool call generated by the model.
id	string	The unique ID of the function tool call.
name*	string	The name of the function.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls.

ImageGenerationCallobject

The output of an image generation tool call.

id	string	The unique ID of the image generation tool call.
prompt	any	The prompt used to generate the image.
result	any	The generated image encoded in base64 (OpenAI-compatible: bare base64, no data-URL prefix), or `null` while the call is still in progress or has failed. The image format can be determined from the decoded magic bytes (typically JPEG or PNG).
status	string	The status of the image generation tool call. One of `in_progress`, `generating`, `completed` or `failed`.
type*	enum	Type tag for [`ImageGenerationCall`]. Serializes as `"image_generation_call"`.	image_generation_call

IncompleteDetailsobject | object | object | …

Details about why a response is incomplete.

InputTokensDetailsobject

cached_tokens*

integer

Token cached by xAI from previous requests and reused for this request.

format: int32

LocalShellSkillobject

A skill available in the local shell environment.

description*	string	A description of what the skill does.
name*	string	The name of the skill.
path*	string	The path to the directory containing the skill (with a SKILL.md file).

McpCallobject

The output of a MCP tool call.

arguments*	string	A JSON string of the arguments passed to the tool.
error	string	The error message of the MCP tool call.
id	string	The unique ID of the MCP tool call.
name*	string	The name of the tool that was run.
output*	string	The output of the MCP tool call.
server_label*	string	The label of the MCP server running the tool.
status	string	The status of the MCP tool call.
type*	string	The type of the MCP tool call. Always `mcp_call`.

ModelOutputany | any | any | …

ModelResponseConfigurationobject

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

ModelResponseFormatobject | object | object

Response format parameter for structured outputs.

ModelToolany | any | object | …

Definition of one tool that the model can call.

ModelToolChoicestring | object

Parameter to control how model chooses the tools.

ModelUsageobject

context_details	ContextDetails	Token counts for the latest context sent to / produced by the model. For agentic responses this reflects the most recent step rather than the cumulative total. Informational only — not used for billing.	nullable
cost_in_nano_usd	any	Cost in nano US dollars for this request.	format: int64
cost_in_usd_ticks	any	Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10'000'000'000 ticks in one dollar.	format: int64
input_tokens*	integer	Number of input tokens used.	format: int32
input_tokens_details*	InputTokensDetails	Breakdown of the input tokens.
num_server_side_tools_used*	integer	Number of server side tools used.	format: int32
num_sources_used*	integer	Number of sources used (for live search).	format: int32
output_tokens*	integer	Number of output tokens used.	format: int32
output_tokens_details*	OutputTokensDetails	Breakdown of the output tokens.
server_side_tool_usage_details	ServerSideToolUsageDetails	Details about the server side tool usage.	nullable
total_tokens*	integer	Total tokens used.	format: int32

OutputMessageobject

An output message from the model.

content*	OutputMessageContent[]	Content of the output message.
id	string	The unique ID of the output message.
role*	string	The role of the output message, which can be `assistant` or `tool`.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the output message, which is always `message`.

OutputMessageContentobject | object

OutputTokensDetailsobject

reasoning_tokens*

integer

Tokens generated by the model for reasoning.

format: int32

Reasoningobject

The reasoning done by the model.

content	ReasoningText[]	The reasoning text contents.
encrypted_content	any	The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`.
id	string	The unique ID of the reasoning content.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
summary*	SummaryText[]	The summarized reasoning text contents.
type*	string	The type of the object, which is always `reasoning`.

ReasoningConfigurationobject

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.
generate_summary	any	Only included for compatibility.
summary	any	A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`.

ReasoningTextobject

text*	string	Reasoning done by the model.
type*	string	The type of the object, which is always `reasoning_text`.

ServerSideToolUsageDetailsobject

code_interpreter_calls*	integer	Number of code interpreter calls.	format: int32
document_search_calls*	integer	Number of document search calls.	format: int32
file_search_calls*	integer	Number of file search calls.	format: int32
image_generation_calls*	integer	Number of image generation calls.	format: int32
mcp_calls*	integer	Number of MCP calls.	format: int32
web_search_calls*	integer	Number of web search calls.	format: int32
x_posts_fetched*	integer	Number of X posts fetched across all X search calls, including nested parent/quote posts and every post of a fetched thread, without de-duplication. X search is billed per fetched item.	format: int32
x_search_calls*	integer	Number of X search calls.	format: int32
x_users_fetched*	integer	Number of X user profiles fetched across all X search calls, without de-duplication. X search is billed per fetched item.	format: int32

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

ShellCallobject

A shell command call emitted by the model for local execution.

action*	ShellCallAction	The shell commands and limits that describe how to run the tool call.
call_id*	string	The unique ID of the shell tool call generated by the model.
environment	ShellEnvironment	The environment for the shell tool call.	nullable
id	string	The unique ID of the shell call item.
status	string	Status of the item. One of `completed`, `in_progress` or `incomplete`.
type*	string	The type of the output item, which is always `shell_call`.

ShellCallActionobject

The shell commands and limits that describe how to run the tool call.

commands*	string[]	The commands to run.
max_output_length	any	Optional maximum number of characters to return from each command.	format: int32
timeout_ms	any	Optional timeout in milliseconds for the commands.	format: int64
type	any	The type of the action, which is always `exec`.

ShellEnvironmentobject

The environment configuration for a shell tool.

skills	LocalShellSkill[]	An optional list of skills available in the local environment.
type*	string	The type of the environment. Currently only `local` is supported.

SummaryTextobject

text*	string	Summary of the reasoning done by the model.
type*	string	The type of the object, which is always `summary_text`.

TokenLogProbobject

bytes	any	The ASCII encoding of the output character.
logprob*	number	The log probability of returning this token.	format: float
token*	string	The token.
top_logprobs*	TopLogProb[]	An array of the most likely tokens to return at this token position.

ToolSearchCallobject

A server-side tool search call made by the model.

arguments	any	The arguments of the tool search call: `{"query": ..., "limit": ...}`.
call_id	any	Always `null`; present for OpenAI compatibility.
execution	string	Where the search runs. Always `server`.
id*	string	The unique ID of the tool search call item.
status	string	Status of the item. One of `in_progress`, `completed` or `incomplete` (a failed search).
type*	enum	Type tag for [`ToolSearchCall`]; a single-variant enum (not a `String`) for the same untagged-enum disambiguation as [`ImageGenerationCallType`].	tool_search_call

ToolSearchOutputobject

The tool definitions loaded by a completed tool search call.

call_id	any	Always `null`; present for OpenAI compatibility.
execution	string	Where the search ran. Always `server`.
id*	string	The unique ID of the tool search output item.
status	string	Status of the item. Always `completed`.
tools	any[]	The loaded tool definitions, echoed in the shape they were supplied in.
type*	enum	Type tag for [`ToolSearchOutput`]. Serializes as `"tool_search_output"`. See [`ToolSearchCallType`] for why this is a single-variant enum.	tool_search_output

TopLogProbobject

bytes	any	The ASCII encoding of the output character.
logprob*	number	The log probability of returning this token.	format: float
token*	string	The token.

WebSearchActionobject | object | object

WebSearchCallobject

The output of a web search tool call.

action*	object \| object \| object	An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find).
id	string	The unique ID of the web search tool call.
status	string	The status of the web search tool call.
type*	string	The type of the web search tool call. Always `web_search_call`.

WebSearchFiltersobject

allowed_domains	any	List of website domains (without protocol specification or subdomains) to restrict search results to (e.g., ["example.com"]). A maximum of 5 websites can be allowed. Use this as a whitelist to limit results to only these specific sites; no other websites will …	items ≤ 5
excluded_domains	any	List of website domains (without protocol specification or subdomains) to exclude from search results (e.g., ["example.com"]). Use this to prevent results from unwanted sites. A maximum of 5 websites can be excluded. This parameter cannot be set together with …	items ≤ 5

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.

WebSearchSourceobject

type*	string	The type of source.
url	string	The URL of the source.

WebSearchUserLocationobject

city	any	City of the user's location.
country	any	Two-letter ISO 3166-1 alpha-2 country code, like US, GB, etc.
region	any	Region of the user's location.
timezone	any	Timezone of the user's location, IANA timezone like America/Chicago, Europe/London, etc.
type*	string	Type is always `"approximate"`.

Validate a payload

before you spend tokens

shell

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