openapi: 3.2.0 info: title: xAI's REST Responses API description: REST API for xAI compatible with other providers. license: name: '' version: 1.0.0 tags: - name: Responses paths: /v1/responses: post: tags: - Responses summary: Generates a response based on text or image prompts. operationId: handle_generic_model_request requestBody: content: application/json: schema: $ref: '#/components/schemas/ModelRequest' example: input: - role: system content: You are a helpful assistant that can answer questions and help with tasks. - role: user content: What is 101*3? model: latest required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ModelResponse' example: created_at: 1754475266 id: ad5663da-63e6-86c6-e0be-ff15effa8357 max_output_tokens: null model: latest object: response output: - content: - type: output_text text: 101 multiplied by 3 is 303. logprobs: null annotations: [] id: msg_ad5663da-63e6-86c6-e0be-ff15effa8357 role: assistant type: message status: completed parallel_tool_calls: true previous_response_id: null reasoning: null temperature: null text: format: type: text tool_choice: auto tools: [] top_p: null usage: input_tokens: 32 input_tokens_details: cached_tokens: 8 output_tokens: 9 output_tokens_details: reasoning_tokens: 110 total_tokens: 151 num_sources_used: 0 num_server_side_tools_used: 0 user: null incomplete_details: null status: completed store: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '422': description: Unprocessable Entity. There are missing fields in the request body. security: - bearerAuth: [] /v1/responses/{response_id}: get: tags: - Responses summary: Retrieve a previously generated response operationId: handle_get_stored_completion_request parameters: - name: response_id in: path description: The response id returned by a previous create response request. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ModelResponse' example: created_at: 1754475266 id: ad5663da-63e6-86c6-e0be-ff15effa8357 max_output_tokens: null model: latest object: response output: - content: - type: output_text text: 101 multiplied by 3 is 303. logprobs: null annotations: [] id: msg_ad5663da-63e6-86c6-e0be-ff15effa8357 role: assistant type: message status: completed - id: '' summary: - text: 'First, the user asked: "What is 101*3?" This is a simple multiplication: 101 multiplied by 3. Calculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303. I should respond helpfully and directly, as per my system prompt: "You are a helpful assistant that can answer questions and help with tasks." Keep the response concise and accurate. No need for extra fluff unless it adds value. Final answer: 303.' type: summary_text type: reasoning status: completed parallel_tool_calls: true previous_response_id: null reasoning: null temperature: null text: format: type: text tool_choice: auto tools: [] top_p: null usage: prompt_tokens: 32 completion_tokens: 9 total_tokens: 151 prompt_tokens_details: text_tokens: 32 audio_tokens: 0 image_tokens: 0 cached_tokens: 8 completion_tokens_details: reasoning_tokens: 110 audio_tokens: 0 accepted_prediction_tokens: 0 rejected_prediction_tokens: 0 num_sources_used: 0 user: null incomplete_details: null status: completed store: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No responses could be found with the given response_id. security: - bearerAuth: [] delete: tags: - Responses summary: Delete a previously generated response operationId: handle_delete_stored_completion_request parameters: - name: response_id in: path description: The response id returned by a previous create response request. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/DeleteStoredCompletionResponse' example: id: ad5663da-63e6-86c6-e0be-ff15effa8357 object: response deleted: true '400': description: Bad request. The request is invalid or an invalid API key is provided. '404': description: Not found. No responses could be found with the given response_id. security: - bearerAuth: [] components: schemas: ServerSideToolUsageDetails: type: object required: - web_search_calls - x_search_calls - code_interpreter_calls - file_search_calls - mcp_calls - document_search_calls properties: code_interpreter_calls: type: integer format: int32 description: Number of code interpreter calls. document_search_calls: type: integer format: int32 description: Number of document search calls. file_search_calls: type: integer format: int32 description: Number of file search calls. mcp_calls: type: integer format: int32 description: Number of MCP calls. web_search_calls: type: integer format: int32 description: Number of web search calls. x_search_calls: type: integer format: int32 description: Number of X search calls. ShellCallAction: type: object description: The shell commands and limits that describe how to run the tool call. required: - commands properties: commands: type: array items: type: string description: The commands to run. max_output_length: type: - integer - 'null' format: int32 description: Optional maximum number of characters to return from each command. timeout_ms: type: - integer - 'null' format: int64 description: Optional timeout in milliseconds for the commands. type: type: - string - 'null' description: The type of the action, which is always `exec`. OutputTokensDetails: type: object required: - reasoning_tokens properties: reasoning_tokens: type: integer format: int32 description: Tokens generated by the model for reasoning. FunctionDefinition: type: object description: Definition of the tool call made available to the model. required: - name - parameters properties: description: type: - string - 'null' description: A description of the function to indicate to the model when to call it. name: type: string description: 'The name of the function. If the model calls the function, this name is used in the response.' parameters: description: 'A JSON schema describing the function parameters. The model _should_ follow the schema, however, this is not enforced at the moment.' strict: type: - boolean - 'null' description: Not supported. Only maintained for compatibility reasons. SummaryText: type: object required: - text - type properties: text: type: string description: Summary of the reasoning done by the model. type: type: string description: The type of the object, which is always `summary_text`. WebSearchCall: type: object description: The output of a web search tool call. required: - type - action properties: action: $ref: '#/components/schemas/WebSearchAction' description: '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: type: string description: The unique ID of the web search tool call. status: type: string description: The status of the web search tool call. type: type: string description: The type of the web search tool call. Always `web_search_call`. ShellCall: type: object description: A shell command call emitted by the model for local execution. required: - action - call_id - type properties: action: $ref: '#/components/schemas/ShellCallAction' description: The shell commands and limits that describe how to run the tool call. call_id: type: string description: The unique ID of the shell tool call generated by the model. environment: oneOf: - type: 'null' - $ref: '#/components/schemas/ShellEnvironment' description: The environment for the shell tool call. id: type: string description: The unique ID of the shell call item. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The type of the output item, which is always `shell_call`. ModelTool: oneOf: - allOf: - $ref: '#/components/schemas/FunctionDefinition' - type: object description: A function that the model can call. required: - type properties: type: type: string enum: - function description: A function that the model can call. - allOf: - $ref: '#/components/schemas/WebSearchOptions' - type: object properties: allowed_domains: type: - array - 'null' items: type: string description: 'List of website domains to allow in the search results. This parameter act as a whitelist where only those websites can be selected. A maximum of 5 websites can be selected. Note: This parameter cannot be set with `excluded_domains`.' example: - wikipedia.com maxItems: 5 enable_image_search: type: - boolean - 'null' description: 'When true, activates the image search server-side tool, enabling the model to search for images alongside the standard web search.' enable_image_understanding: type: - boolean - 'null' description: Enable image understanding during web search. excluded_domains: type: - array - 'null' items: type: string description: 'List of website domains to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. Note: This parameter cannot be set with `allowed_domains`' example: - wikipedia.com maxItems: 5 external_web_access: type: - boolean - 'null' description: 'Control whether the web search tool fetches live content or uses only cached content. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' filters: oneOf: - type: 'null' - $ref: '#/components/schemas/WebSearchFilters' description: Filters to apply to the search results. Compatible with OpenAI's API. search_context_size: type: - string - 'null' description: 'High level guidance for the amount of context window space to use for the search. Available values are `low`, `medium`, or `high`. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' user_location: oneOf: - type: 'null' - $ref: '#/components/schemas/WebSearchUserLocation' description: 'The user location to use for the search. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' - type: object description: Search the web. required: - type properties: type: type: string enum: - web_search description: Search the web. - type: object description: Search X. required: - type properties: allowed_x_handles: type: - array - 'null' items: type: string description: 'List of X Handles of the users from whom to consider the posts. Note: This parameter cannot be set with `excluded_x_handles`.' example: - elonmusk maxItems: 10 enable_image_understanding: type: - boolean - 'null' description: Enable image understanding during X search. enable_video_understanding: type: - boolean - 'null' description: Enable video understanding during X search. excluded_x_handles: type: - array - 'null' items: type: string description: 'List of X Handles of the users from whom to exclude the posts. Note: This parameter cannot be set with `allowed_x_handles`.' example: - elonmusk maxItems: 10 from_date: type: - string - 'null' format: date description: 'Date from which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-06-24' to_date: type: - string - 'null' format: date description: 'Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-12-24' type: type: string enum: - x_search - type: object description: Search the knowledge bases. required: - vector_store_ids - type properties: filters: description: 'A filter to apply. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' max_num_results: type: - integer - 'null' format: int32 example: 10 minimum: 1 ranking_options: description: 'Ranking options for search. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' type: type: string enum: - file_search vector_store_ids: type: array items: type: string description: List of vector store IDs to search within. example: - collection_id_1 - collection_id_2 maxItems: 10 - type: object description: Execute code. required: - type properties: container: description: 'The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code. For OpenAI API compatibility ONLY. Request will be rejected if this field is set.' type: type: string enum: - code_interpreter - type: object description: A remote MCP server to use. required: - server_label - server_url - type properties: allowed_tools: type: - array - 'null' items: type: string authorization: type: - string - 'null' connector_id: type: - string - 'null' headers: type: - object - 'null' additionalProperties: type: string propertyNames: type: string require_approval: type: - string - 'null' server_description: type: - string - 'null' server_label: type: string server_url: type: string type: type: string enum: - mcp - type: object description: A local shell execution tool. required: - environment - type properties: environment: $ref: '#/components/schemas/ShellEnvironment' description: The environment configuration for the shell tool. type: type: string enum: - shell description: Definition of one tool that the model can call. ReasoningConfiguration: type: object properties: effort: type: - string - 'null' description: Constrains how hard a reasoning model thinks before responding. Possible values are `low` (uses fewer reasoning tokens), `medium` and `high` (uses more reasoning tokens). default: medium generate_summary: type: - string - 'null' description: Only included for compatibility. summary: type: - string - 'null' description: 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`. Reasoning: type: object description: The reasoning done by the model. required: - summary - type properties: content: type: array items: $ref: '#/components/schemas/ReasoningText' description: The reasoning text contents. encrypted_content: type: - string - 'null' description: The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`. id: type: string description: The unique ID of the reasoning content. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. summary: type: array items: $ref: '#/components/schemas/SummaryText' description: The summarized reasoning text contents. type: type: string description: The type of the object, which is always `reasoning`. CodeInterpreterCall: type: object description: The output of a code interpreter tool call. required: - type - outputs properties: code: type: string description: The code of the code interpreter tool call. id: type: string description: The unique ID of the code interpreter tool call. outputs: type: array items: $ref: '#/components/schemas/CodeInterpreterOutput' description: The outputs of the code interpreter tool call. status: type: string description: The status of the code interpreter tool call. type: type: string description: The type of the code interpreter tool call. Always `code_interpreter_call`. WebSearchAction: oneOf: - type: object description: Action type "search" - Performs a web search query. required: - query - type properties: query: type: string description: The search query. sources: type: array items: $ref: '#/components/schemas/WebSearchSource' description: The sources used in the search. type: type: string enum: - search - type: object description: Action type "open_page" - Opens a specific URL from search results. required: - url - type properties: type: type: string enum: - open_page url: type: string description: The URL of the page to open. - type: object description: 'Action type "find": Searches for a pattern within a loaded page.' required: - source - pattern - type properties: pattern: type: string description: The pattern or text to search for within the page. source: $ref: '#/components/schemas/WebSearchSource' description: The source of the page to search in. type: type: string enum: - find ModelRequest: type: object description: The request body for `/v1/responses` endpoint. required: - input properties: background: type: - boolean - 'null' description: (Unsupported) Whether to process the response asynchronously in the background. default: false context_management: type: - array - 'null' items: {} description: Optional context-management directives (e.g. compaction). Parsed but not yet executed. include: type: - array - 'null' items: type: string description: What additional output data to include in the response. Currently the only supported value is `reasoning.encrypted_content` which returns an encrypted version of the reasoning tokens. input: $ref: '#/components/schemas/ModelInput' description: The input passed to the model. Can be text, image or file. instructions: type: - string - 'null' description: An alternate way to specify the system prompt. Note that this cannot be used alongside `previous_response_id`, where the system prompt of the previous message will be used. logprobs: type: - boolean - 'null' description: 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. default: false max_output_tokens: type: - integer - 'null' format: int32 description: Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. max_turns: type: - integer - 'null' format: int32 description: 'Maximum number of agentic tool calling turns allowed for this request. If not set, defaults to the server''s global cap. This parameter will be ignored for any non-agentic requests.' metadata: description: Not supported. Only maintained for compatibility reasons. model: type: string description: Model name for the model to use. Obtainable from or . example: latest parallel_tool_calls: type: - boolean - 'null' description: Whether to allow the model to run parallel tool calls. default: true previous_response_id: type: - string - 'null' description: The ID of the previous response from the model. prompt_cache_key: type: - string - 'null' description: Plumbed to x-grok-conv-id for Open Responses compatibility, used for routing. reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ReasoningConfiguration' description: Reasoning configuration. Only for reasoning models. search_parameters: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchParameters' description: Set the parameters to be used for searched data. Takes precedence over `web_search_preview` tool if specified in the tools. service_tier: type: - string - 'null' description: Not supported. Only maintained for compatibility reasons. store: type: - boolean - 'null' description: Whether to store the input message(s) and model response for later retrieval. default: true stream: type: - boolean - 'null' description: '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 example: true temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 example: 0.2 maximum: 2 minimum: 0 text: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelResponseConfiguration' description: Settings for customizing a text response from the model. tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelToolChoice' description: '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 or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.' tools: type: - array - 'null' items: $ref: '#/components/schemas/ModelTool' description: A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.`web_search_preview` tool, if specified, will be overridden by `search_parameters`. maxItems: 128 top_logprobs: type: - integer - 'null' format: int32 description: 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. maximum: 8 minimum: 0 top_p: type: - number - 'null' format: float description: 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 recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 truncation: type: - string - 'null' description: Not supported. Only maintained for compatibility reasons. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. SearchParameters: type: object description: Parameters to control realtime data. properties: from_date: type: - string - 'null' format: date description: 'Date from which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-06-24' max_search_results: type: - integer - 'null' format: int32 description: Maximum number of search results to use. default: 15 maximum: 30 minimum: 1 mode: type: - string - 'null' description: '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 the data.' default: auto example: auto return_citations: type: - boolean - 'null' description: Whether to return citations in the response or not. default: true sources: type: - array - 'null' items: $ref: '#/components/schemas/SearchSource' description: List of sources to search in. If no sources specified, the model will look over the web and X by default. to_date: type: - string - 'null' format: date description: 'Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See .' example: '2024-12-24' TokenLogProb: type: object required: - token - logprob - top_logprobs properties: bytes: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: The ASCII encoding of the output character. logprob: type: number format: float description: The log probability of returning this token. token: type: string description: The token. top_logprobs: type: array items: $ref: '#/components/schemas/TopLogProb' description: An array of the most likely tokens to return at this token position. Annotation: type: object required: - type - url properties: end_index: type: - integer - 'null' format: int32 description: The end index of the annotation. start_index: type: - integer - 'null' format: int32 description: The summary of the annotation. title: type: - string - 'null' description: The title of the annotation. type: type: string description: The type of the annotation. Only supported type currently is `url_citation`. url: type: string description: The URL of the web resource. ModelResponseFormat: oneOf: - type: object description: Specify text response format, always `"text"`. required: - type properties: type: type: string enum: - text - type: object description: Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this. required: - type properties: type: type: string enum: - json_object - type: object description: Specify json_schema response format with a given schema. Type is always `"json_schema"`. required: - schema - type properties: description: type: - string - 'null' description: Only included for compatibility. name: type: - string - 'null' description: Only included for compatibility. schema: description: A json schema representing the desired response schema. strict: type: - boolean - 'null' description: Only included for compatibility. type: type: string enum: - json_schema description: Response format parameter for structured outputs. ShellCallOutputResult: type: object description: The content of a shell tool call output that was emitted. required: - outcome properties: outcome: $ref: '#/components/schemas/ShellCallOutcome' description: The outcome of the command execution. stderr: type: string description: The standard error output that was captured. stdout: type: string description: The standard output that was captured. FunctionToolCall: type: object description: A tool call to run a function. required: - arguments - call_id - name - type properties: arguments: type: string description: The arguments to pass to the function, as a JSON string. call_id: type: string description: The unique ID of the function tool call generated by the model. id: type: string description: The unique ID of the function tool call. name: type: string description: The name of the function. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: '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.' FunctionToolCallOutput: type: object description: The output of a function tool call. required: - call_id - output - type properties: call_id: type: string description: The unique ID of the function tool call generated by the model. output: type: string description: The output of the function tool call, as a JSON string. type: type: string description: The type of the function tool call, which is always `function_call_output`. WebSearchSource: type: object required: - type properties: type: type: string description: The type of source. url: type: string description: The URL of the source. IncompleteDetails: oneOf: - type: object required: - reason properties: reason: type: string enum: - max_output_tokens - type: object required: - reason properties: reason: type: string enum: - max_prompt_tokens - type: object required: - reason properties: reason: type: string enum: - max_time_limit description: Details about why a response is incomplete. DeleteStoredCompletionResponse: type: object description: Response to delete a stored completion. required: - id - object - deleted properties: deleted: type: boolean description: Whether the response was successfully deleted. id: type: string description: The response_id to be deleted. object: type: string description: The deleted object type, which is always `response`. ModelInputPart: oneOf: - type: object description: Message input to the model. required: - content - role properties: content: $ref: '#/components/schemas/ModelInputContent' description: Text, image or audio input. name: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages. role: type: string description: The role of the message. Possible values are `user`, `assistant`, `system` and `developer`. type: type: - string - 'null' description: The type of the message, which is always `message`. - allOf: - $ref: '#/components/schemas/ModelOutput' description: The model output from previous responses. - allOf: - $ref: '#/components/schemas/FunctionToolCallOutput' description: The output of a function call. - allOf: - $ref: '#/components/schemas/ShellCallOutput' description: The output of a shell call. - allOf: - $ref: '#/components/schemas/CompactionOutputItem' description: A compaction item from a previous `/v1/responses/compact` call. SearchSource: oneOf: - type: object required: - type properties: excluded_x_handles: type: - array - 'null' items: type: string description: 'List of X handles to exclude from the search results. X posts returned will not include any posts authored by these handles.' included_x_handles: type: - array - 'null' items: type: string description: ' NOTE: `included_x_handles` and `x_handles` are the same parameter. `included_x_handles` is the new name but we keep both for backward compatibility. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`.' post_favorite_count: type: - integer - 'null' format: int32 description: The minimum favorite count of the X posts to consider. post_view_count: type: - integer - 'null' format: int32 description: The minimum view count of the X posts to consider. type: type: string enum: - x x_handles: type: - array - 'null' items: type: string description: 'DEPRECATED in favor of `included_x_handles`. Use `included_x_handles` instead. X Handles of the users from whom to consider the posts. Only available if mode is `auto`, `on` or `x`.' deprecated: true - type: object required: - type properties: allowed_websites: type: - array - 'null' items: type: string description: 'List of website to allow in the search results. This parameter act as a whitelist where only those websites can be selected. A maximum of 5 websites can be selected. Note 1: If no relevant information is found on those websites, the number of results returned might be smaller than `max_search_results`. Note 2: This parameter cannot be set with `excluded_websites`.' example: - wikipedia.com maxItems: 5 country: type: - string - 'null' format: iso3166-1-alpha-2 description: 'ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See .' example: BE excluded_websites: type: - array - 'null' items: type: string description: 'List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded. Note 2: This parameter cannot be set with `allowed_websites`' example: - wikipedia.com maxItems: 5 safe_search: type: - boolean - 'null' description: If set to true, mature content won't be considered during the search. Default to `true`. type: type: string enum: - web - type: object required: - type properties: country: type: - string - 'null' format: iso3166-1-alpha-2 description: 'ISO alpha-2 code of the country. If the country is set, only data coming from this country will be considered. See .' example: BE excluded_websites: type: - array - 'null' items: type: string description: 'List of website to exclude from the search results without protocol specification or subdomains. A maximum of 5 websites can be excluded.' example: - foxnews.com maxItems: 5 safe_search: type: - boolean - 'null' description: If set to true, mature content won't be considered during the search. Default to `true`. type: type: string enum: - news - type: object required: - links - type properties: links: type: array items: type: string description: Links of the RSS feeds. example: - https://status.x.ai/feed.xml maxItems: 1 minItems: 1 type: type: string enum: - rss ModelUsage: type: object required: - input_tokens - input_tokens_details - output_tokens - output_tokens_details - total_tokens - num_sources_used - num_server_side_tools_used properties: cost_in_nano_usd: type: - integer - 'null' format: int64 description: Cost in nano US dollars for this request. cost_in_usd_ticks: type: - integer - 'null' format: int64 description: '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*.' input_tokens: type: integer format: int32 description: Number of input tokens used. input_tokens_details: $ref: '#/components/schemas/InputTokensDetails' description: Breakdown of the input tokens. num_server_side_tools_used: type: integer format: int32 description: Number of server side tools used. num_sources_used: type: integer format: int32 description: Number of sources used (for live search). output_tokens: type: integer format: int32 description: Number of output tokens used. output_tokens_details: $ref: '#/components/schemas/OutputTokensDetails' description: Breakdown of the output tokens. server_side_tool_usage_details: oneOf: - type: 'null' - $ref: '#/components/schemas/ServerSideToolUsageDetails' description: Details about the server side tool usage. total_tokens: type: integer format: int32 description: Total tokens used. ModelResponseConfiguration: type: object properties: format: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelResponseFormat' description: '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.' ShellCallOutcome: oneOf: - type: object description: The command exited normally. required: - exit_code - type properties: exit_code: type: integer format: int32 description: The exit code of the command. type: type: string enum: - exit - type: object description: The command timed out. required: - type properties: type: type: string enum: - timeout description: The outcome of a shell command execution. CustomToolCall: type: object description: The output of a custom tool call. required: - call_id - name - type - id properties: call_id: type: string description: The unique ID of the function tool call generated by the model. id: type: string description: The status of the custom tool call. input: type: string description: The unique ID of the custom tool call, name: type: string description: An identifier used to map this custom tool call to a tool call output. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The input for the custom tool call generated by the model. CodeInterpreterOutput: oneOf: - type: object description: The output of the code interpreter tool call. required: - logs - type properties: logs: type: string description: The output of the code interpreter tool call. type: type: string enum: - logs - type: object description: The error of the code interpreter tool call. required: - url - type properties: type: type: string enum: - image url: type: string description: The error of the code interpreter tool call. ModelInput: oneOf: - type: string description: Text input. - type: array items: $ref: '#/components/schemas/ModelInputPart' description: A list of input items to the model. Can be of different types. description: Content of the input passed to a `/v1/response` request. ModelToolChoice: oneOf: - type: string description: Controls tool access by the model. `"none"` makes model ignore tools, `"auto"` let the model automatically decide whether to call a tool, `"required"` forces model to pick a tool to call. - type: object required: - type - name properties: name: type: string description: Name of the function to use. type: type: string description: Type is always `"function"`. description: Parameter to control how model chooses the tools. CompactionOutputItem: type: object description: 'A compaction item from a previous `/v1/responses/compact` call. Accepted as input in `/v1/responses` calls. Clients must treat `encrypted_content` as opaque — do not parse or depend on its internal structure.' required: - type - encrypted_content properties: encrypted_content: type: string description: The encrypted content of the compacted conversation. id: type: - string - 'null' description: The unique ID of the compaction item (e.g. `cmp_`). type: type: string description: The type of the item. Always `"compaction"`. ModelInputContent: oneOf: - type: string description: Text input. - type: array items: $ref: '#/components/schemas/ModelInputContentItem' description: A list of input items to the model. Can include text and images. ShellEnvironment: type: object description: The environment configuration for a shell tool. required: - type properties: skills: type: array items: $ref: '#/components/schemas/LocalShellSkill' description: An optional list of skills available in the local environment. type: type: string description: The type of the environment. Currently only `local` is supported. ReasoningText: type: object required: - text - type properties: text: type: string description: Reasoning done by the model. type: type: string description: The type of the object, which is always `reasoning_text`. FileSearchCall: type: object description: The output of a web search tool call. required: - type - queries - results properties: id: type: string description: The unique ID of the file search tool call. queries: type: array items: type: string description: The queries used to search for files. results: type: array items: $ref: '#/components/schemas/FileSearchResult' description: The results of the file search tool call. status: type: string description: The status of the file search tool call. type: type: string description: The type of the file search tool call. Always `file_search_call`. OutputMessage: type: object description: An output message from the model. required: - content - role - type properties: content: type: array items: $ref: '#/components/schemas/OutputMessageContent' description: Content of the output message. id: type: string description: The unique ID of the output message. role: type: string description: The role of the output message, which can be `assistant` or `tool`. status: type: string description: Status of the item. One of `completed`, `in_progress` or `incomplete`. type: type: string description: The type of the output message, which is always `message`. ModelResponse: type: object description: The response body for `/v1/responses` endpoint. required: - created_at - id - model - object - output - parallel_tool_calls - text - tool_choice - tools - status - store - metadata - background - service_tier - truncation - top_logprobs - presence_penalty - frequency_penalty properties: background: type: boolean description: 'OpenResponses compatibility fields. Not used at the moment. Just for OpenResponses compatibility. Whether to process the response asynchronously in the background.' default: false completed_at: type: - integer - 'null' format: int64 description: The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed. created_at: type: integer format: int64 description: The Unix timestamp (in seconds) for the response creation time. error: description: An error object returned when the model fails to generate a response. frequency_penalty: type: number format: float description: (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. id: type: string description: Unique ID of the response. incomplete_details: oneOf: - type: 'null' - $ref: '#/components/schemas/IncompleteDetails' description: Details about why the response is incomplete. instructions: type: - string - 'null' description: A system (or developer) message inserted into the model's context. max_output_tokens: type: - integer - 'null' format: int32 description: Max number of tokens that can be generated in a response. This includes both output and reasoning tokens. max_tool_calls: type: - integer - 'null' format: int32 description: The maximum number of tool calls allowed for this response. metadata: description: Only included for compatibility. model: type: string description: Model name used to generate the response. object: type: string description: The object type of this resource. Always set to `response`. output: type: array items: $ref: '#/components/schemas/ModelOutput' description: The response generated by the model. parallel_tool_calls: type: boolean description: Whether to allow the model to run parallel tool calls. presence_penalty: type: number format: float description: (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. previous_response_id: type: - string - 'null' description: The ID of the previous response from the model. prompt_cache_key: type: - string - 'null' description: The cache key used for the prompt for routing to the correct engine. reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ReasoningConfiguration' description: Reasoning configuration. Only for reasoning models. safety_identifier: type: - string - 'null' description: A stable identifier used to help detect users of your application that may be violating xAI's usage policies. service_tier: type: string description: Specifies the processing tier used for serving the request. default: default status: type: string description: Status of the response. One of `completed`, `in_progress` or `incomplete`. store: type: boolean description: Whether to store the input message(s) and model response for later retrieval. default: true temperature: type: - number - 'null' format: float description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. default: 1 maximum: 2 minimum: 0 text: $ref: '#/components/schemas/ModelResponseConfiguration' description: Settings for customizing a text response from the model. tool_choice: $ref: '#/components/schemas/ModelToolChoice' description: '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": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.' tools: type: array items: $ref: '#/components/schemas/ModelTool' description: A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported. maxItems: 128 top_logprobs: type: integer format: int32 description: An integer between 0 and 8 specifying the number of most likely tokens to return at each token position. top_p: type: - number - 'null' format: float description: 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 recommended to alter this or `temperature` but not both. default: 1 maximum: 1 exclusiveMinimum: 0 truncation: type: string description: The truncation strategy to use for the model response. default: disabled usage: oneOf: - type: 'null' - $ref: '#/components/schemas/ModelUsage' description: Token usage information. user: type: - string - 'null' description: A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. InputTokensDetails: type: object required: - cached_tokens properties: cached_tokens: type: integer format: int32 description: Token cached by xAI from previous requests and reused for this request. WebSearchUserLocation: type: object required: - type properties: city: type: - string - 'null' description: City of the user's location. country: type: - string - 'null' description: Two-letter ISO 3166-1 alpha-2 country code, like US, GB, etc. region: type: - string - 'null' description: Region of the user's location. timezone: type: - string - 'null' description: Timezone of the user's location, IANA timezone like America/Chicago, Europe/London, etc. type: type: string description: Type is always `"approximate"`. FileSearchResult: type: object required: - file_id - filename - text properties: file_id: type: string description: The file ID of the file search result. filename: type: string description: The filename of the file search result. score: type: number format: double description: 'The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent.' text: type: string description: The text of the file search result. WebSearchOptions: type: object properties: filters: description: Only included for compatibility. search_context_size: type: - string - 'null' description: This field included for compatibility reason with OpenAI's API. It is mapped to `max_search`. default: medium example: medium user_location: description: Only included for compatibility. ModelInputContentItem: oneOf: - type: object description: Text input. required: - text - type properties: text: type: string description: Text input. type: type: string enum: - input_text - type: object description: Text output (used in compact response output items). required: - text - type properties: text: type: string type: type: string enum: - output_text - type: object description: 'Image input. Note: Storing and fetching images is not fully supported at the moment.' required: - image_url - type properties: file_id: type: - string - 'null' description: Only included for compatibility. image_url: type: string description: A public URL of image prompt, only available for vision models. type: type: string enum: - input_image - type: object description: File input. required: - type properties: file_data: type: - string - 'null' description: 'Inline file bytes (base64 encoded). When set, the file content is provided directly in the request and does NOT need to be uploaded to the Files API first. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' file_id: type: - string - 'null' description: 'The file ID from the Files API. Set this to reference a previously-uploaded file. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' file_url: type: - string - 'null' description: 'Public URL for a file attachment. When set, the file content is fetched from this URL. Exactly one of `file_id`, `file_data`, or `file_url` should be set.' filename: type: - string - 'null' description: 'Filename for inline uploads. Required when `file_data` is set.' mime_type: type: - string - 'null' description: Optional MIME type for inline uploads (e.g. "application/pdf"). type: type: string enum: - input_file ModelOutput: oneOf: - allOf: - $ref: '#/components/schemas/OutputMessage' - allOf: - $ref: '#/components/schemas/FunctionToolCall' - allOf: - $ref: '#/components/schemas/Reasoning' - allOf: - $ref: '#/components/schemas/WebSearchCall' - allOf: - $ref: '#/components/schemas/FileSearchCall' - allOf: - $ref: '#/components/schemas/CodeInterpreterCall' - allOf: - $ref: '#/components/schemas/McpCall' - allOf: - $ref: '#/components/schemas/CustomToolCall' - allOf: - $ref: '#/components/schemas/ShellCall' TopLogProb: type: object required: - token - logprob properties: bytes: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: The ASCII encoding of the output character. logprob: type: number format: float description: The log probability of returning this token. token: type: string description: The token. WebSearchFilters: type: object properties: allowed_domains: type: - array - 'null' items: type: string description: '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 be considered. If no relevant information is found on these websites, the number of results returned might be smaller than `max_search_results` set in `SearchParameters`. Note: This parameter cannot be set together with `excluded_domains`.' example: - example.com maxItems: 5 excluded_domains: type: - array - 'null' items: type: string description: '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 `allowed_domains`.' example: - example.com maxItems: 5 OutputMessageContent: oneOf: - type: object description: Text output. required: - text - type properties: annotations: type: array items: $ref: '#/components/schemas/Annotation' description: Citations. logprobs: type: array items: $ref: '#/components/schemas/TokenLogProb' description: The log probabilities of each output token returned in the content of message. text: type: string description: The text output from the model. type: type: string enum: - output_text - type: object description: Refusal. required: - refusal - type properties: refusal: type: string description: The reason for the refusal. type: type: string enum: - refusal ShellCallOutput: type: object description: The output of a shell tool call, sent by the client after local execution. required: - call_id - output - type properties: call_id: type: string description: The unique ID of the shell tool call generated by the model. max_output_length: type: - integer - 'null' format: int32 description: 'The maximum length of the shell command output. Generated by the model and should be passed back with the raw output.' output: type: array items: $ref: '#/components/schemas/ShellCallOutputResult' description: An array of shell call output contents. type: type: string description: The type of the output item, which is always `shell_call_output`. LocalShellSkill: type: object description: A skill available in the local shell environment. required: - name - description - path properties: description: type: string description: A description of what the skill does. name: type: string description: The name of the skill. path: type: string description: The path to the directory containing the skill (with a SKILL.md file). McpCall: type: object description: The output of a MCP tool call. required: - type - name - server_label - arguments - output properties: arguments: type: string description: A JSON string of the arguments passed to the tool. error: type: string description: The error message of the MCP tool call. id: type: string description: The unique ID of the MCP tool call. name: type: string description: The name of the tool that was run. output: type: string description: The output of the MCP tool call. server_label: type: string description: The label of the MCP server running the tool. status: type: string description: The status of the MCP tool call. type: type: string description: The type of the MCP tool call. Always `mcp_call`. securitySchemes: bearerAuth: type: http scheme: bearer