List conversation items

List all items for a conversation with the given ID.

Request

GET

https://ai.api.cloud.yandex.net/v1/conversations/{conversation_id}/items

Path parameters

Name

Description

conversation_id

Type: string

The ID of the conversation to list items for.

Example: ``

Query parameters

Name

Description

after

Type: string

An item ID to list items after, used in pagination.

Example: ``

include

Type: IncludeEnum[]

Specify additional output data to include in the model response.

Example: ``

limit

Type: integer

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Default: 20

order

Type: string

The order to return the input items in. Default is desc. - asc: Return the input items in ascending order. - desc: Return the input items in descending order.

Enum: asc, desc

IncludeEnum

Specify additional output data to include in the model response. Currently supported values are:

  • web_search_call.action.sources: Include the sources of the web search tool call.
  • code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items.
  • computer_call_output.output.image_url: Include image urls from the computer call output.
  • file_search_call.results: Include the search results of the file search tool call.
  • message.input_image.image_url: Include image urls from the input message.
  • message.output_text.logprobs: Include logprobs with assistant messages.
  • reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program).

Type: string

Enum: file_search_call.results, web_search_call.results, web_search_call.action.sources, message.input_image.image_url, computer_call_output.output.image_url, code_interpreter_call.outputs, reasoning.encrypted_content, message.output_text.logprobs

Responses

200 OK

OK

Body

application/json
{
          "object": "list",
          "data": [
            {
              "type": "message",
              "id": "example",
              "status": "in_progress",
              "role": "unknown",
              "content": [
                null
              ],
              "phase": "commentary"
            }
          ],
          "has_more": true,
          "first_id": "example",
          "last_id": "example"
        }

Name

Description

data

Type: ConversationItem[]

A list of conversation items.

Example
[
          {
            "type": "message",
            "id": "example",
            "status": "in_progress",
            "role": "unknown",
            "content": [
              {}
            ],
            "phase": "commentary"
          }
        ]

first_id

Type: string

The ID of the first item in the list.

Example: example

has_more

Type: boolean

Whether there are more items available.

last_id

Type: string

The ID of the last item in the list.

Example: example

object

Type: string

The type of object returned, must be list.

Const: list

Example: example

MessageStatus

Type: string

Enum: in_progress, completed, incomplete

MessageRole

Type: string

Enum: unknown, user, assistant, system, critic, discriminator, developer, tool

InputTextContent

A text input to the model.

Name

Description

text

Type: string

The text input to the model.

Example: example

type

Type: string

The type of the input item. Always input_text.

Default: input_text

Const: input_text
Example
{
          "type": "input_text",
          "text": "example"
        }

FileCitationBody

A citation to a file.

Name

Description

file_id

Type: string

The ID of the file.

Example: example

filename

Type: string

The filename of the file cited.

Example: example

index

Type: integer

The index of the file in the list of files.

type

Type: string

The type of the file citation. Always file_citation.

Default: file_citation

Const: file_citation
Example
{
          "type": "file_citation",
          "file_id": "example",
          "index": 0,
          "filename": "example"
        }

UrlCitationBody

A citation for a web resource used to generate a model response.

Name

Description

end_index

Type: integer

The index of the last character of the URL citation in the message.

start_index

Type: integer

The index of the first character of the URL citation in the message.

title

Type: string

The title of the web resource.

Example: example

type

Type: string

The type of the URL citation. Always url_citation.

Default: url_citation

Const: url_citation

url

Type: string

The URL of the web resource.

Example: example
Example
{
          "type": "url_citation",
          "url": "example",
          "start_index": 0,
          "end_index": 0,
          "title": "example"
        }

ContainerFileCitationBody

A citation for a container file used to generate a model response.

Name

Description

container_id

Type: string

The ID of the container file.

Example: example

end_index

Type: integer

The index of the last character of the container file citation in the message.

file_id

Type: string

The ID of the file.

Example: example

filename

Type: string

The filename of the container file cited.

Example: example

start_index

Type: integer

The index of the first character of the container file citation in the message.

type

Type: string

The type of the container file citation. Always container_file_citation.

Default: container_file_citation

Const: container_file_citation
Example
{
          "type": "container_file_citation",
          "container_id": "example",
          "file_id": "example",
          "start_index": 0,
          "end_index": 0,
          "filename": "example"
        }

FilePath

A path to a file.

Name

Description

file_id

Type: string

The ID of the file.

Example: example

index

Type: integer

The index of the file in the list of files.

type

Type: string

The type of the file path. Always file_path.

Const: file_path

Example: example
Example
{
          "type": "file_path",
          "file_id": "example",
          "index": 0
        }

Annotation

An annotation that applies to a span of output text.

One of 4 types

  • File citation

    Type: FileCitationBody

    A citation to a file.

    Example
    {
          "type": "file_citation",
          "file_id": "example",
          "index": 0,
          "filename": "example"
        }

  • URL citation

    Type: UrlCitationBody

    A citation for a web resource used to generate a model response.

    Example
    {
          "type": "url_citation",
          "url": "example",
          "start_index": 0,
          "end_index": 0,
          "title": "example"
        }

  • Container file citation

    Type: ContainerFileCitationBody

    A citation for a container file used to generate a model response.

    Example
    {
          "type": "container_file_citation",
          "container_id": "example",
          "file_id": "example",
          "start_index": 0,
          "end_index": 0,
          "filename": "example"
        }

  • File path

    Type: FilePath

    A path to a file.

    Example
    {
          "type": "file_path",
          "file_id": "example",
          "index": 0
        }
Example
{
          "type": "file_citation",
          "file_id": "example",
          "index": 0,
          "filename": "example"
        }

TopLogProb

The top log probability of a token.

Name

Description

bytes

Type: integer[]

Example
[
          0
        ]

logprob

Type: number

token

Type: string

Example: example
Example
{
          "token": "example",
          "logprob": 0.5,
          "bytes": [
            0
          ]
        }

LogProb

The log probability of a token.

Name

Description

bytes

Type: integer[]

Example
[
          0
        ]

logprob

Type: number

token

Type: string

Example: example

top_logprobs

Type: TopLogProb[]

Example
[
          {
            "token": "example",
            "logprob": 0.5,
            "bytes": [
              0
            ]
          }
        ]
Example
{
          "token": "example",
          "logprob": 0.5,
          "bytes": [
            0
          ],
          "top_logprobs": [
            {
              "token": "example",
              "logprob": 0.5,
              "bytes": [
                0
              ]
            }
          ]
        }

OutputTextContent

A text output from the model.

Name

Description

annotations

Type: Annotation[]

The annotations of the text output.

Example
[
          {
            "type": "file_citation",
            "file_id": "example",
            "index": 0,
            "filename": "example"
          }
        ]

logprobs

Type: LogProb[]

Example
[
          {
            "token": "example",
            "logprob": 0.5,
            "bytes": [
              0
            ],
            "top_logprobs": [
              {
                "token": "example",
                "logprob": 0.5,
                "bytes": [
                  0
                ]
              }
            ]
          }
        ]

text

Type: string

The text output from the model.

Example: example

type

Type: string

The type of the output text. Always output_text.

Default: output_text

Const: output_text
Example
{
          "type": "output_text",
          "text": "example",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "example",
              "index": 0,
              "filename": "example"
            }
          ],
          "logprobs": [
            {
              "token": "example",
              "logprob": 0.5,
              "bytes": [
                0
              ],
              "top_logprobs": [
                {
                  "token": "example",
                  "logprob": 0.5,
                  "bytes": [
                    null
                  ]
                }
              ]
            }
          ]
        }

TextContent

A text content.

Name

Description

text

Type: string

Example: example

type

Type: string

Default: text

Const: text
Example
{
          "type": "text",
          "text": "example"
        }

SummaryTextContent

A summary text from the model.

Name

Description

text

Type: string

A summary of the reasoning output from the model so far.

Example: example

type

Type: string

The type of the object. Always summary_text.

Default: summary_text

Const: summary_text
Example
{
          "type": "summary_text",
          "text": "example"
        }

ReasoningTextContent

Reasoning text from the model.

Name

Description

text

Type: string

The reasoning text from the model.

Example: example

type

Type: string

The type of the reasoning text. Always reasoning_text.

Default: reasoning_text

Const: reasoning_text
Example
{
          "type": "reasoning_text",
          "text": "example"
        }

RefusalContent

A refusal from the model.

Name

Description

refusal

Type: string

The refusal explanation from the model.

Example: example

type

Type: string

The type of the refusal. Always refusal.

Default: refusal

Const: refusal
Example
{
          "type": "refusal",
          "refusal": "example"
        }

ImageDetail

Type: string

Enum: low, high, auto, original

InputImageContent

An image input to the model.

Name

Description

detail

Type: ImageDetail

The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

Enum: low, high, auto, original

type

Type: string

The type of the input item. Always input_image.

Default: input_image

Const: input_image

file_id
Any of 2 types

  • Type: string

    The ID of the file to be sent to the model.

    Example: example

  • Type: null

    Example: null

Example: example

image_url
Any of 2 types

  • Type: string

    The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "input_image",
          "image_url": "example",
          "file_id": "example",
          "detail": "low"
        }

ComputerScreenshotContent

A screenshot of a computer.

Name

Description

detail

Type: ImageDetail

The detail level of the screenshot image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

Enum: low, high, auto, original

file_id
Any of 2 types

  • Type: string

    The identifier of an uploaded file that contains the screenshot.

    Example: example

  • Type: null

    Example: null

Example: example

image_url
Any of 2 types

  • Type: string

    The URL of the screenshot image.

    Example: example

  • Type: null

    Example: null

Example: example

type

Type: string

Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

Default: computer_screenshot

Const: computer_screenshot
Example
{
          "type": "computer_screenshot",
          "image_url": "example",
          "file_id": "example",
          "detail": "low"
        }

FileInputDetail

Type: string

Enum: low, high

InputFileContent

A file input to the model.

Name

Description

type

Type: string

The type of the input item. Always input_file.

Default: input_file

Const: input_file

detail

Type: FileInputDetail

The detail level of the file to be sent to the model. Use low for the default rendering behavior, or high to render the file at higher quality. Defaults to low.

Enum: low, high

file_data

Type: string

The content of the file to be sent to the model.

Example: example

file_id
Any of 2 types

  • Type: string

    The ID of the file to be sent to the model.

    Example: example

  • Type: null

    Example: null

Example: example

file_url

Type: string

The URL of the file to be sent to the model.

Example: example

filename

Type: string

The name of the file to be sent to the model.

Example: example
Example
{
          "type": "input_file",
          "file_id": "example",
          "filename": "example",
          "file_data": "example",
          "file_url": "example",
          "detail": "low"
        }

MessagePhase-2

Type: string

Enum: commentary, final_answer

Message

A message to or from the model.

Name

Description

content
Type: array
One of 9 types

  • Input text

    Type: InputTextContent

    A text input to the model.

    Example
    {
          "type": "input_text",
          "text": "example"
        }

  • Output text

    Type: OutputTextContent

    A text output from the model.

    Example
    {
          "type": "output_text",
          "text": "example",
          "annotations": [
            {
              "type": "file_citation",
              "file_id": "example",
              "index": 0,
              "filename": "example"
            }
          ],
          "logprobs": [
            {
              "token": "example",
              "logprob": 0.5,
              "bytes": [
                0
              ],
              "top_logprobs": [
                {
                  "token": "example",
                  "logprob": 0.5,
                  "bytes": [
                    null
                  ]
                }
              ]
            }
          ]
        }

  • Text Content

    Type: TextContent

    A text content.

    Example
    {
          "type": "text",
          "text": "example"
        }

  • Summary text

    Type: SummaryTextContent

    A summary text from the model.

    Example
    {
          "type": "summary_text",
          "text": "example"
        }

  • Reasoning text

    Type: ReasoningTextContent

    Reasoning text from the model.

    Example
    {
          "type": "reasoning_text",
          "text": "example"
        }

  • Refusal

    Type: RefusalContent

    A refusal from the model.

    Example
    {
          "type": "refusal",
          "refusal": "example"
        }

  • Input image

    Type: InputImageContent

    An image input to the model.

    Example
    {
          "type": "input_image",
          "image_url": "example",
          "file_id": "example",
          "detail": "low"
        }

  • Computer screenshot

    Type: ComputerScreenshotContent

    A screenshot of a computer.

    Example
    {
          "type": "computer_screenshot",
          "image_url": "example",
          "file_id": "example",
          "detail": "low"
        }

  • Input file

    Type: InputFileContent

    A file input to the model.

    Example
    {
          "type": "input_file",
          "file_id": "example",
          "filename": "example",
          "file_data": "example",
          "file_url": "example",
          "detail": "low"
        }

The content of the message

Example
[
          {
            "type": "input_text",
            "text": "example"
          }
        ]

id

Type: string

The unique ID of the message.

Example: example

role

Type: MessageRole

The role of the message. One of unknown, user, assistant, system, critic, discriminator, developer, or tool.

Enum: unknown, user, assistant, system, critic, discriminator, developer, tool

status

Type: MessageStatus

The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

Enum: in_progress, completed, incomplete

type

Type: string

The type of the message. Always set to message.

Default: message

Const: message

phase
Any of 2 types

  • Type: MessagePhase-2

    Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). Not used for user messages.

    Enum: commentary, final_answer

  • Type: null

    Example: null

Example: commentary
Example
{
          "type": "message",
          "id": "example",
          "status": "in_progress",
          "role": "unknown",
          "content": [
            {
              "type": "input_text",
              "text": "example"
            }
          ],
          "phase": "commentary"
        }

FunctionToolCall

A tool call to run a function.

Name

Description

arguments

Type: string

A JSON string of the arguments to pass to the function.

Example: example

call_id

Type: string

The unique ID of the function tool call generated by the model.

Example: example

name

Type: string

The name of the function to run.

Example: example

type

Type: string

The type of the function tool call. Always function_call.

Const: function_call

Example: example

id

Type: string

The unique ID of the function tool call.

Example: example

namespace

Type: string

The namespace of the function to run.

Example: example

status

Type: string

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

Enum: in_progress, completed, incomplete
Example
{
          "id": "example",
          "type": "function_call",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "arguments": "example",
          "status": "in_progress"
        }

FunctionToolCallResource

All of 2 types

  • Function tool call

    Type: FunctionToolCall

    A tool call to run a function.

    Example
    {
          "id": "example",
          "type": "function_call",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "arguments": "example",
          "status": "in_progress"
        }
  • Type: object

    id

    Type: string

    The unique ID of the function tool call.

    Example: example

    status

    Type: FunctionCallStatus

    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

    Enum: in_progress, completed, incomplete

    created_by

    Type: string

    The identifier of the actor that created the item.

    Example: example
    Example
    {
          "id": "example",
          "status": "in_progress",
          "created_by": "example"
        }
Example
{
          "id": "example",
          "type": "function_call",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "arguments": "example",
          "status": "in_progress",
          "created_by": "example"
        }

FunctionAndCustomToolCallOutput

One of 3 types

  • Input text

    Type: InputTextContent

    A text input to the model.

    Example
    {
          "type": "input_text",
          "text": "example"
        }

  • Input image

    Type: InputImageContent

    An image input to the model.

    Example
    {
          "type": "input_image",
          "image_url": "example",
          "file_id": "example",
          "detail": "low"
        }

  • Input file

    Type: InputFileContent

    A file input to the model.

    Example
    {
          "type": "input_file",
          "file_id": "example",
          "filename": "example",
          "file_data": "example",
          "file_url": "example",
          "detail": "low"
        }
Example
{
          "type": "input_text",
          "text": "example"
        }

FunctionToolCallOutput

The output of a function tool call.

Name

Description

call_id

Type: string

The unique ID of the function tool call generated by the model.

Example: example

output
One of: string output or output content list

  • string output

    Type: string

    A string of the output of the function call.

    Example: example

  • output content list

    Type: FunctionAndCustomToolCallOutput[]

    Text, image, or file output of the function call.

    Example
    [
          {
            "type": "input_text",
            "text": "example"
          }
        ]

The output from the function call generated by your code.
Can be a string or an list of output content.

Example: example

type

Type: string

The type of the function tool call output. Always function_call_output.

Const: function_call_output

Example: example

id

Type: string

The unique ID of the function tool call output. Populated when this item is returned via API.

Example: example

status

Type: string

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

Enum: in_progress, completed, incomplete
Example
{
          "id": "example",
          "type": "function_call_output",
          "call_id": "example",
          "output": "example",
          "status": "in_progress"
        }

FunctionToolCallOutputResource

All of 2 types

  • Function tool call output

    Type: FunctionToolCallOutput

    The output of a function tool call.

    Example
    {
          "id": "example",
          "type": "function_call_output",
          "call_id": "example",
          "output": "example",
          "status": "in_progress"
        }
  • Type: object

    id

    Type: string

    The unique ID of the function call tool output.

    Example: example

    status

    Type: FunctionCallOutputStatusEnum

    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

    Enum: in_progress, completed, incomplete

    created_by

    Type: string

    The identifier of the actor that created the item.

    Example: example
    Example
    {
          "id": "example",
          "status": "in_progress",
          "created_by": "example"
        }
Example
{
          "id": "example",
          "type": "function_call_output",
          "call_id": "example",
          "output": "example",
          "status": "in_progress",
          "created_by": "example"
        }

VectorStoreFileAttributes

Any of 2 types
  • Type: object

    [additional]
    One of 3 types

    • Type: string

      Max length: 512

      Example: example

    • Type: number

    • Type: boolean

    Example: example

    Set of key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

    Max properties: 16

    Example
    {}

  • Type: unknown

    Example: null

Default: null

FileSearchToolCall

The results of a File Search tool call.

Name

Description

id

Type: string

The unique ID of the file search tool call.

Example: example

queries

Type: string[]

The queries used to search for files.

Example
[
          "example"
        ]

status

Type: string

The status of the file search tool call. One of in_progress, searching, incomplete or failed,

Enum: in_progress, searching, completed, incomplete, failed

type

Type: string

The type of the file search tool call. Always file_search_call.

Const: file_search_call

Example: example

results
Any of 2 types

  • Type: object[]

    attributes

    Type: VectorStoreFileAttributes

    Default: null

    Example
    {}

    file_id

    Type: string

    The unique ID of the file.

    Example: example

    filename

    Type: string

    The name of the file.

    Example: example

    score

    Type: number

    The relevance score of the file - a value between 0 and 1.

    text

    Type: string

    The text that was retrieved from the file.

    Example: example

    The results of the file search tool call.

    Example
    [
          {
            "file_id": "example",
            "text": "example",
            "filename": "example",
            "attributes": null,
            "score": 0.5
          }
        ]

  • Type: null

    Example: null

Example
[
          {
            "file_id": "example",
            "text": "example",
            "filename": "example",
            "attributes": null,
            "score": 0.5
          }
        ]
Example
{
          "id": "example",
          "type": "file_search_call",
          "status": "in_progress",
          "queries": [
            "example"
          ],
          "results": [
            {
              "file_id": "example",
              "text": "example",
              "filename": "example",
              "attributes": null,
              "score": 0.5
            }
          ]
        }

WebSearchActionSearch

Action type "search" - Performs a web search query.

Name

Description

query

Type: string

[DEPRECATED] The search query.

Example: example

type

Type: string

The action type.

Const: search

Example: example

queries

Type: string[]

The search queries.

Example
[
          "example"
        ]

sources
Type: Web search source

type

Type: string

The type of source. Always url.

Const: url

Example: example

url

Type: string

The URL of the source.

Example: example

The sources used in the search.

Example
[
          {
            "type": "url",
            "url": "example"
          }
        ]
Example
{
          "type": "search",
          "query": "example",
          "queries": [
            "example"
          ],
          "sources": [
            {
              "type": "url",
              "url": "example"
            }
          ]
        }

WebSearchActionOpenPage

Action type "open_page" - Opens a specific URL from search results.

Name

Description

type

Type: string

The action type.

Const: open_page

Example: example

url
Any of 2 types

  • Type: string<uri>

    Example: https://example.com

  • Type: null

    Example: null

The URL opened by the model.

Example: https://example.com
Example
{
          "type": "open_page",
          "url": "https://example.com"
        }

WebSearchActionFind

Action type "find_in_page": Searches for a pattern within a loaded page.

Name

Description

pattern

Type: string

The pattern or text to search for within the page.

Example: example

type

Type: string

The action type.

Const: find_in_page

Example: example

url

Type: string<uri>

The URL of the page searched for the pattern.

Example: https://example.com
Example
{
          "type": "find_in_page",
          "url": "https://example.com",
          "pattern": "example"
        }

WebSearchToolCall

The results of a web search tool call.

Name

Description

action

Type: object

One of 3 types

  • Search action

    Type: WebSearchActionSearch

    Action type "search" - Performs a web search query.

    Example
    {
          "type": "search",
          "query": "example",
          "queries": [
            "example"
          ],
          "sources": [
            {
              "type": "url",
              "url": "example"
            }
          ]
        }

  • Open page action

    Type: WebSearchActionOpenPage

    Action type "open_page" - Opens a specific URL from search results.

    Example
    {
          "type": "open_page",
          "url": "https://example.com"
        }

  • Find action

    Type: WebSearchActionFind

    Action type "find_in_page": Searches for a pattern within a loaded page.

    Example
    {
          "type": "find_in_page",
          "url": "https://example.com",
          "pattern": "example"
        }

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_in_page).

Example
{
          "type": "search",
          "query": "example",
          "queries": [
            "example"
          ],
          "sources": [
            {
              "type": "url",
              "url": "example"
            }
          ]
        }

id

Type: string

The unique ID of the web search tool call.

Example: example

status

Type: string

The status of the web search tool call.

Enum: in_progress, searching, completed, failed

type

Type: string

The type of the web search tool call. Always web_search_call.

Const: web_search_call

Example: example
Example
{
          "id": "example",
          "type": "web_search_call",
          "status": "in_progress",
          "action": {
            "type": "search",
            "query": "example",
            "queries": [
              "example"
            ],
            "sources": [
              {
                "type": "url",
                "url": "example"
              }
            ]
          }
        }

ImageGenToolCall

An image generation request made by the model.

Name

Description

id

Type: string

The unique ID of the image generation call.

Example: example

result
Any of 2 types

  • Type: string

    The generated image encoded in base64.

    Example: example

  • Type: null

    Example: null

Example: example

status

Type: string

The status of the image generation call.

Enum: in_progress, completed, generating, failed

type

Type: string

The type of the image generation call. Always image_generation_call.

Const: image_generation_call

Example: example
Example
{
          "type": "image_generation_call",
          "id": "example",
          "status": "in_progress",
          "result": "example"
        }

ToolSearchExecutionType

Type: string

Enum: server, client

ToolSearchCall

Name

Description

arguments

Type: unknown

Arguments used for the tool search call.

Example: null

call_id
Any of 2 types

  • Type: string

    The unique ID of the tool search call generated by the model.

    Example: example

  • Type: null

    Example: null

Example: example

execution

Type: ToolSearchExecutionType

Whether tool search was executed by the server or by the client.

Enum: server, client

id

Type: string

The unique ID of the tool search call item.

Example: example

status

Type: FunctionCallStatus

The status of the tool search call item that was recorded.

Enum: in_progress, completed, incomplete

type

Type: string

The type of the item. Always tool_search_call.

Default: tool_search_call

Const: tool_search_call

created_by

Type: string

The identifier of the actor that created the item.

Example: example
Example
{
          "type": "tool_search_call",
          "id": "example",
          "call_id": "example",
          "execution": "server",
          "arguments": null,
          "status": "in_progress",
          "created_by": "example"
        }

FunctionTool

Defines a function in your own code the model can choose to call. Learn more about function calling.

Name

Description

name

Type: string

The name of the function to call.

Example: example

parameters
Any of 2 types

  • Type: object

    [additional]

    Type: unknown

    Example: null

    A JSON schema object describing the parameters of the function.

    Example
    {}

  • Type: null

    Example: null

Example
{}

strict
Any of 2 types

  • Type: boolean

    Whether to enforce strict parameter validation. Default true.

  • Type: null

    Example: null

Example: true

type

Type: string

The type of the function tool. Always function.

Default: function

Const: function

defer_loading

Type: boolean

Whether this function is deferred and loaded via tool search.

description
Any of 2 types

  • Type: string

    A description of the function. Used by the model to determine whether or not to call the function.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "function",
          "name": "example",
          "description": "example",
          "parameters": {},
          "strict": true,
          "defer_loading": true
        }

RankerVersionType

Type: string

Enum: auto, default-2024-11-15

HybridSearchOptions

Name

Description

embedding_weight

Type: number

The weight of the embedding in the reciprocal ranking fusion.

text_weight

Type: number

The weight of the text in the reciprocal ranking fusion.
Example
{
          "embedding_weight": 0.5,
          "text_weight": 0.5
        }

RankingOptions

Name

Description

hybrid_search

Type: HybridSearchOptions

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

Example
{
          "embedding_weight": 0.5,
          "text_weight": 0.5
        }

ranker

Type: RankerVersionType

The ranker to use for the file search.

Enum: auto, default-2024-11-15

score_threshold

Type: number

The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.
Example
{
          "ranker": "auto",
          "score_threshold": 0.5,
          "hybrid_search": {
            "embedding_weight": 0.5,
            "text_weight": 0.5
          }
        }

ComparisonFilter

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

Name

Description

key

Type: string

The key to compare against the value.

Example: example

type

Type: string

Specifies the comparison operator:

  • eq: equals - ne: not equal - gt: greater than - gte: greater than or equal - lt: less than - lte: less than or equal - in: in - nin: not in

Default: eq

Enum: eq, ne, gt, gte, lt, lte, in, nin

value
One of 4 types

  • Type: string

    Example: example

  • Type: number

  • Type: boolean

  • Type: array
    One of 2 types

    • Type: string

      Example: example

    • Type: number

    Example
    [
          "example"
        ]

The value to compare against the attribute key; supports string, number, or boolean types.

Example: example
Example
{
          "type": "eq",
          "key": "example",
          "value": "example"
        }

CompoundFilter

Combine multiple filters using and or or.

Name

Description

filters
Type: array
One of 2 types

  • Comparison Filter

    Type: ComparisonFilter

    A filter used to compare a specified attribute key to a given value using a defined comparison operation.

    Example
    {
          "type": "eq",
          "key": "example",
          "value": "example"
        }

  • Type: unknown

    Example: null

Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.

Example
[
          {
            "type": "eq",
            "key": "example",
            "value": "example"
          }
        ]

type

Type: string

Type of operation: and or or.

Enum: and, or
Example
{
          "type": "and",
          "filters": [
            {
              "type": "eq",
              "key": "example",
              "value": "example"
            }
          ]
        }

Filters

Any of 2 types

  • Comparison Filter

    Type: ComparisonFilter

    A filter used to compare a specified attribute key to a given value using a defined comparison operation.

    Example
    {
          "type": "eq",
          "key": "example",
          "value": "example"
        }

  • Compound Filter

    Type: CompoundFilter

    Combine multiple filters using and or or.

    Example
    {
          "type": "and",
          "filters": [
            {
              "type": "eq",
              "key": "example",
              "value": "example"
            }
          ]
        }
Example
{
          "type": "eq",
          "key": "example",
          "value": "example"
        }

FileSearchTool

A tool that searches for relevant content from uploaded files. Learn more about the File Search tool.

Name

Description

type

Type: string

The type of the file search tool. Always file_search.

Default: file_search

Const: file_search

vector_store_ids

Type: string[]

The IDs of the vector stores to search.

Example
[
          "example"
        ]

filters
Any of 2 types

  • Type: Filters

    A filter to apply.

    Example
    {
          "type": "eq",
          "key": "example",
          "value": "example"
        }

  • Type: null

    Example: null

Example
{
          "type": "eq",
          "key": "example",
          "value": "example"
        }

max_num_results

Type: integer

The maximum number of results to return. This number should be between 1 and 50 inclusive.

ranking_options

Type: RankingOptions

Ranking options for search.

Example
{
          "ranker": "auto",
          "score_threshold": 0.5,
          "hybrid_search": {
            "embedding_weight": 0.5,
            "text_weight": 0.5
          }
        }
Example
{
          "type": "file_search",
          "vector_store_ids": [
            "example"
          ],
          "max_num_results": 0,
          "ranking_options": {
            "ranker": "auto",
            "score_threshold": 0.5,
            "hybrid_search": {
              "embedding_weight": 0.5,
              "text_weight": 0.5
            }
          },
          "filters": {
            "type": "eq",
            "key": "example",
            "value": "example"
          }
        }

WebSearchApproximateLocation

Any of 2 types
  • Type: Web search approximate location

    city
    Any of 2 types

    • Type: string

      Free text input for the city of the user, e.g. San Francisco.

      Example: example

    • Type: null

      Example: null

    Example: example

    country
    Any of 2 types

    • Type: string

      The two-letter ISO country code of the user, e.g. US.

      Example: example

    • Type: null

      Example: null

    Example: example

    region
    Any of 2 types

    • Type: string

      Free text input for the region of the user, e.g. California.

      Example: example

    • Type: null

      Example: null

    Example: example

    timezone
    Any of 2 types

    • Type: string

      The IANA timezone of the user, e.g. America/Los_Angeles.

      Example: example

    • Type: null

      Example: null

    Example: example

    type

    Type: string

    The type of location approximation. Always approximate.

    Default: approximate

    Const: approximate

    The approximate location of the user.

    Example
    {
          "type": "approximate",
          "country": "example",
          "region": "example",
          "city": "example",
          "timezone": "example"
        }

  • Type: null

    Example: null

Example
{
          "type": "approximate",
          "country": "example",
          "region": "example",
          "city": "example",
          "timezone": "example"
        }

WebSearchTool

Search the Internet for sources related to the prompt. Learn more about the web search tool.

Name

Description

type

Type: string

The type of the web search tool. One of web_search or web_search_2025_08_26.

Default: web_search

Enum: web_search, web_search_2025_08_26

filters
Any of 2 types

  • Type: object

    allowed_domains
    Any of 2 types

    • Allowed domains for the search.

      Type: string[]

      Allowed domains for the search. If not provided, all domains are allowed.
      Subdomains of the provided domains are allowed as well.

      Default: []

      Example
      [
          "example"
        ]

    • Type: null

      Example: null

    Example
    [
          "example"
        ]

    Filters for the search.

    Example
    {
          "allowed_domains": []
        }

  • Type: null

    Example: null

Example
{
          "allowed_domains": []
        }

search_context_size

Type: string

High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.

Default: medium

Enum: low, medium, high

user_location

Type: WebSearchApproximateLocation

Example
{
          "type": "approximate",
          "country": "example",
          "region": "example",
          "city": "example",
          "timezone": "example"
        }
Example
{
          "type": "web_search",
          "filters": {
            "allowed_domains": []
          },
          "user_location": {
            "type": "approximate",
            "country": "example",
            "region": "example",
            "city": "example",
            "timezone": "example"
          },
          "search_context_size": "medium"
        }

MCPToolFilter

A filter object to specify which tools are allowed.

Name

Description

read_only

Type: boolean

Indicates whether or not a tool modifies data or is read-only. If an

MCP server is annotated with readOnlyHint,
it will match this filter.

tool_names

Type: string[]

List of allowed tool names.

Example
[
          "example"
        ]
Example
{
          "tool_names": [
            "example"
          ],
          "read_only": true
        }

MCPTool

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

Name

Description

server_label

Type: string

A label for this MCP server, used to identify it in tool calls.

Example: example

type

Type: string

The type of the MCP tool. Always mcp.

Const: mcp

Example: example

allowed_tools
Any of 2 types
  • One of 2 types

    • MCP allowed tools

      Type: string[]

      A string array of allowed tool names

      Example
      [
          "example"
        ]

    • MCP tool filter

      Type: MCPToolFilter

      A filter object to specify which tools are allowed.

      Example
      {
          "tool_names": [
            "example"
          ],
          "read_only": true
        }

    List of allowed tool names or a filter object.

    Example
    [
          "example"
        ]

  • Type: null

    Example: null

Example
[
          "example"
        ]

authorization

Type: string

An OAuth access token that can be used with a remote MCP server,
either with a custom MCP server URL or a service connector. Your
application must handle the OAuth authorization flow and provide the token here.

Example: example

connector_id

Type: string

Identifier for service connectors. One of server_url or connector_id must be provided.

Enum: connector_dropbox, connector_gmail, connector_googlecalendar, connector_googledrive, connector_microsoftteams, connector_outlookcalendar, connector_outlookemail, connector_sharepoint

defer_loading

Type: boolean

Whether this MCP tool is deferred and discovered via tool search.

headers
Any of 2 types

  • Type: object

    [additional]

    Type: string

    Example: example

    Optional HTTP headers to send to the MCP server. Use for
    authentication or other purposes.

    Example
    {}

  • Type: null

    Example: null

Example
{}

require_approval
Any of 2 types
  • One of: MCP tool approval filter or MCP tool approval setting

    • Type: MCP tool approval filter

      always

      MCP tool filter

      Type: MCPToolFilter

      A filter object to specify which tools are allowed.

      Example
      {
          "tool_names": [
            "example"
          ],
          "read_only": true
        }

      never

      MCP tool filter

      Type: MCPToolFilter

      A filter object to specify which tools are allowed.

      Example
      {
          "tool_names": [
            "example"
          ],
          "read_only": true
        }

      Specify which of the MCP server's tools require approval.
      Can be always, never, or a filter object associated with tools
      that require approval.

      Example
      {
          "always": {
            "tool_names": [
              "example"
            ],
            "read_only": true
          },
          "never": null
        }

    • MCP tool approval setting

      Type: string

      Specify a single approval policy for all tools. One of always or
      never. When set to always, all tools will require approval. When set to never, all tools will not require approval.

      Enum: always, never

    Specify which of the MCP server's tools require approval.

    Default: always

  • Type: null

    Example: null

Example
{
          "always": {
            "tool_names": [
              "example"
            ],
            "read_only": true
          },
          "never": null
        }

server_description

Type: string

Optional description of the MCP server, used to provide more context.

Example: example

server_url

Type: string

The URL for the MCP server. One of server_url or connector_id
must be provided.

Example: example
Example
{
          "type": "mcp",
          "server_label": "example",
          "server_url": "example",
          "connector_id": "connector_dropbox",
          "authorization": "example",
          "server_description": "example",
          "headers": {},
          "allowed_tools": [
            "example"
          ],
          "require_approval": "always",
          "defer_loading": true
        }

ContainerMemoryLimit

Type: string

Enum: 1g, 4g, 16g, 64g

ContainerNetworkPolicyDisabledParam

Name

Description

type

Type: string

Disable outbound network access. Always disabled.

Default: disabled

Const: disabled
Example
{
          "type": "disabled"
        }

ContainerNetworkPolicyDomainSecretParam

Name

Description

domain

Type: string

The domain associated with the secret.

Min length: 1

Example: example

name

Type: string

The name of the secret to inject for the domain.

Min length: 1

Example: example

value

Type: string

The secret value to inject for the domain.

Min length: 1

Max length: 10485760

Example: example
Example
{
          "domain": "example",
          "name": "example",
          "value": "example"
        }

ContainerNetworkPolicyAllowlistParam

Name

Description

allowed_domains

Type: string[]

A list of allowed domains when type is allowlist.

Min items: 1

Example
[
          "example"
        ]

type

Type: string

Allow outbound network access only to specified domains. Always allowlist.

Default: allowlist

Const: allowlist

domain_secrets

Type: ContainerNetworkPolicyDomainSecretParam[]

Optional domain-scoped secrets for allowlisted domains.

Min items: 1

Example
[
          {
            "domain": "example",
            "name": "example",
            "value": "example"
          }
        ]
Example
{
          "type": "allowlist",
          "allowed_domains": [
            "example"
          ],
          "domain_secrets": [
            {
              "domain": "example",
              "name": "example",
              "value": "example"
            }
          ]
        }

AutoCodeInterpreterToolParam

Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

Name

Description

type

Type: string

Always auto.

Default: auto

Const: auto

file_ids

Type: string[]

An optional list of uploaded files to make available to your code.

Max items: 50

Example
[
          "example"
        ]

memory_limit
Any of 2 types

  • Type: ContainerMemoryLimit

    The memory limit for the code interpreter container.

    Enum: 1g, 4g, 16g, 64g

  • Type: null

    Example: null

Example: 1g

network_policy
One of 2 types

Network access policy for the container.

Example
{
          "type": "disabled"
        }
Example
{
          "type": "auto",
          "file_ids": [
            "example"
          ],
          "memory_limit": "1g",
          "network_policy": {
            "type": "disabled"
          }
        }

CodeInterpreterTool

A tool that runs Python code to help generate a response to a prompt.

Name

Description

container
One of 2 types

  • Type: string

    The container ID.

    Example: example

  • CodeInterpreterToolAuto

    Type: AutoCodeInterpreterToolParam

    Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

    Example
    {
          "type": "auto",
          "file_ids": [
            "example"
          ],
          "memory_limit": "1g",
          "network_policy": {
            "type": "disabled"
          }
        }

The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional memory_limit setting.

Example: example

type

Type: string

The type of the code interpreter tool. Always code_interpreter.

Const: code_interpreter

Example: example
Example
{
          "type": "code_interpreter",
          "container": "example"
        }

InputFidelity

Control how much effort the model will exert to match the style and features, especially facial features, of input images.
Supports high and low. Defaults to low.

Type: string

Enum: high, low

ImageGenActionEnum

Type: string

Enum: generate, edit, auto

ImageGenTool

A tool that generates images using the image generation models.

Name

Description

type

Type: string

The type of the image generation tool. Always image_generation.

Const: image_generation

Example: example

action

Type: ImageGenActionEnum

Whether to generate a new image or edit an existing image. Default: auto.

Enum: generate, edit, auto

background

Type: string

CURRENTLY NOT SUPPORTED

Background type for the generated image. One of transparent, opaque, or auto. Default: auto.

Default: auto

Enum: transparent, opaque, auto

input_fidelity
Any of 2 types

  • Type: InputFidelity

    Control how much effort the model will exert to match the style and features, especially facial features, of input images.
    Supports high and low. Defaults to low.

    Enum: high, low

  • Type: null

    Example: null

Example: high

input_image_mask
Type: object

file_id

Type: string

File ID for the mask image.

Example: example

image_url

Type: string

Base64-encoded mask image.

Example: example

CURRENTLY NOT SUPPORTED

Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).

Example
{
          "image_url": "example",
          "file_id": "example"
        }

model
Any of 2 types

  • Type: string

    Example: example

  • Type: string

    The image generation model to use.

    Default: aliceai-image-art-3.0

    Const: aliceai-image-art-3.0

Example: example

moderation

Type: string

CURRENTLY NOT SUPPORTED

Moderation level for the generated image.

Default: auto

Enum: auto, low

output_compression

Type: integer

Compression level for the output image.

Default: 100

Min value: 0

Max value: 100

output_format

Type: string

The output format of the generated image. One of png, webp, or jpeg.

Default: png

Enum: png, webp, jpeg

partial_images

Type: integer

Number of partial images to generate in streaming mode, from 0 (default value) to 3.

Default: 0

Min value: 0

Max value: 3

quality

Type: string

The quality of the generated image. One of low, medium, high, or auto.

Default: auto

Enum: low, medium, high, auto

size

Type: string

The size of the generated image. One of 1024x1024, 1024x1536, 1536x1024, or auto.

Default: auto

Enum: 1024x1024, 1024x1536, 1536x1024, auto
Example
{
          "type": "image_generation",
          "model": "example",
          "quality": "auto",
          "size": "auto",
          "output_format": "png",
          "output_compression": 100,
          "moderation": "auto",
          "background": "auto",
          "input_fidelity": "high",
          "input_image_mask": {
            "image_url": "example",
            "file_id": "example"
          },
          "partial_images": 0,
          "action": "generate"
        }

Tool

A tool that can be used to generate a response.

One of 6 types

  • Function

    Type: FunctionTool

    Defines a function in your own code the model can choose to call. Learn more about function calling.

    Example
    {
          "type": "function",
          "name": "example",
          "description": "example",
          "parameters": {},
          "strict": true,
          "defer_loading": true
        }

  • File search

    Type: FileSearchTool

    A tool that searches for relevant content from uploaded files. Learn more about the File Search tool.

    Example
    {
          "type": "file_search",
          "vector_store_ids": [
            "example"
          ],
          "max_num_results": 0,
          "ranking_options": {
            "ranker": "auto",
            "score_threshold": 0.5,
            "hybrid_search": {
              "embedding_weight": 0.5,
              "text_weight": 0.5
            }
          },
          "filters": {
            "type": "eq",
            "key": "example",
            "value": "example"
          }
        }

  • Web search

    Type: WebSearchTool

    Search the Internet for sources related to the prompt. Learn more about the web search tool.

    Example
    {
          "type": "web_search",
          "filters": {
            "allowed_domains": []
          },
          "user_location": {
            "type": "approximate",
            "country": "example",
            "region": "example",
            "city": "example",
            "timezone": "example"
          },
          "search_context_size": "medium"
        }

  • MCP tool

    Type: MCPTool

    Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

    Example
    {
          "type": "mcp",
          "server_label": "example",
          "server_url": "example",
          "connector_id": "connector_dropbox",
          "authorization": "example",
          "server_description": "example",
          "headers": {},
          "allowed_tools": [
            "example"
          ],
          "require_approval": "always",
          "defer_loading": true
        }

  • Code interpreter

    Type: CodeInterpreterTool

    A tool that runs Python code to help generate a response to a prompt.

    Example
    {
          "type": "code_interpreter",
          "container": "example"
        }

  • Image generation tool

    Type: ImageGenTool

    A tool that generates images using the image generation models.

    Example
    {
          "type": "image_generation",
          "model": "example",
          "quality": "auto",
          "size": "auto",
          "output_format": "png",
          "output_compression": 100,
          "moderation": "auto",
          "background": "auto",
          "input_fidelity": "high",
          "input_image_mask": {
            "image_url": "example",
            "file_id": "example"
          },
          "partial_images": 0,
          "action": "generate"
        }
Example
{
          "type": "function",
          "name": "example",
          "description": "example",
          "parameters": {},
          "strict": true,
          "defer_loading": true
        }

ToolSearchOutput

Name

Description

call_id
Any of 2 types

  • Type: string

    The unique ID of the tool search call generated by the model.

    Example: example

  • Type: null

    Example: null

Example: example

execution

Type: ToolSearchExecutionType

Whether tool search was executed by the server or by the client.

Enum: server, client

id

Type: string

The unique ID of the tool search output item.

Example: example

status

Type: FunctionCallOutputStatusEnum

The status of the tool search output item that was recorded.

Enum: in_progress, completed, incomplete

tools

Type: Tool[]

The loaded tool definitions returned by tool search.

Example
[
          {
            "type": "function",
            "name": "example",
            "description": "example",
            "parameters": {},
            "strict": true,
            "defer_loading": true
          }
        ]

type

Type: string

The type of the item. Always tool_search_output.

Default: tool_search_output

Const: tool_search_output

created_by

Type: string

The identifier of the actor that created the item.

Example: example
Example
{
          "type": "tool_search_output",
          "id": "example",
          "call_id": "example",
          "execution": "server",
          "tools": [
            {
              "type": "function",
              "name": "example",
              "description": "example",
              "parameters": {},
              "strict": true,
              "defer_loading": true
            }
          ],
          "status": "in_progress",
          "created_by": "example"
        }

ReasoningItem

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

Name

Description

id

Type: string

The unique identifier of the reasoning content.

Example: example

summary

Type: SummaryTextContent[]

Reasoning summary content.

Example
[
          {
            "type": "summary_text",
            "text": "example"
          }
        ]

type

Type: string

The type of the object. Always reasoning.

Const: reasoning

Example: example

content

Type: ReasoningTextContent[]

Reasoning text content.

Example
[
          {
            "type": "reasoning_text",
            "text": "example"
          }
        ]

encrypted_content
Any of 2 types

  • Type: string

    The encrypted content of the reasoning item - populated when a response is
    generated with reasoning.encrypted_content in the include parameter.

    Example: example

  • Type: null

    Example: null

Example: example

status

Type: string

The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.

Enum: in_progress, completed, incomplete
Example
{
          "type": "reasoning",
          "id": "example",
          "encrypted_content": "example",
          "summary": [
            {
              "type": "summary_text",
              "text": "example"
            }
          ],
          "content": [
            {
              "type": "reasoning_text",
              "text": "example"
            }
          ],
          "status": "in_progress"
        }

CompactionBody

A compaction item generated by the v1/responses/compact API.

Name

Description

encrypted_content

Type: string

The encrypted content that was produced by compaction.

Example: example

id

Type: string

The unique ID of the compaction item.

Example: example

type

Type: string

The type of the item. Always compaction.

Default: compaction

Const: compaction

created_by

Type: string

The identifier of the actor that created the item.

Example: example
Example
{
          "type": "compaction",
          "id": "example",
          "encrypted_content": "example",
          "created_by": "example"
        }

CodeInterpreterOutputLogs

The logs output from the code interpreter.

Name

Description

logs

Type: string

The logs output from the code interpreter.

Example: example

type

Type: string

The type of the output. Always logs.

Default: logs

Const: logs
Example
{
          "type": "logs",
          "logs": "example"
        }

CodeInterpreterOutputImage

The image output from the code interpreter.

Name

Description

type

Type: string

The type of the output. Always image.

Default: image

Const: image

url

Type: string

The URL of the image output from the code interpreter.

Example: example
Example
{
          "type": "image",
          "url": "example"
        }

CodeInterpreterToolCall

A tool call to run code.

Name

Description

code
Any of 2 types

  • Type: string

    The code to run, or null if not available.

    Example: example

  • Type: null

    Example: null

Example: example

container_id

Type: string

The ID of the container used to run the code.

Example: example

id

Type: string

The unique ID of the code interpreter tool call.

Example: example

outputs
Any of 2 types
  • Type: array
    One of 2 types

    • Code interpreter output logs

      Type: CodeInterpreterOutputLogs

      The logs output from the code interpreter.

      Example
      {
          "type": "logs",
          "logs": "example"
        }

    • Code interpreter output image

      Type: CodeInterpreterOutputImage

      The image output from the code interpreter.

      Example
      {
          "type": "image",
          "url": "example"
        }

    The outputs generated by the code interpreter, such as logs or images.
    Can be null if no outputs are available.

    Example
    [
          {
            "type": "logs",
            "logs": "example"
          }
        ]

  • Type: null

    Example: null

Example
[
          {
            "type": "logs",
            "logs": "example"
          }
        ]

status

Type: string

The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.

Enum: in_progress, completed, incomplete, interpreting, failed

type

Type: string

The type of the code interpreter tool call. Always code_interpreter_call.

Default: code_interpreter_call

Const: code_interpreter_call
Example
{
          "type": "code_interpreter_call",
          "id": "example",
          "status": "in_progress",
          "container_id": "example",
          "code": "example",
          "outputs": [
            {
              "type": "logs",
              "logs": "example"
            }
          ]
        }

LocalShellExecAction

Execute a shell command on the server.

Name

Description

command

Type: string[]

The command to run.

Example
[
          "example"
        ]

env
Type: object

[additional]

Type: string

Example: example

Environment variables to set for the command.

Example
{}

type

Type: string

The type of the local shell action. Always exec.

Default: exec

Const: exec

timeout_ms
Any of 2 types

  • Type: integer

    Optional timeout in milliseconds for the command.

  • Type: null

    Example: null

Example: 0

user
Any of 2 types

  • Type: string

    Optional user to run the command as.

    Example: example

  • Type: null

    Example: null

Example: example

working_directory
Any of 2 types

  • Type: string

    Optional working directory to run the command in.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "exec",
          "command": [
            "example"
          ],
          "timeout_ms": 0,
          "working_directory": "example",
          "env": {},
          "user": "example"
        }

LocalShellToolCall

A tool call to run a command on the local shell.

Name

Description

action

Type: LocalShellExecAction

Execute a shell command on the server.

Example
{
          "type": "exec",
          "command": [
            "example"
          ],
          "timeout_ms": 0,
          "working_directory": "example",
          "env": {},
          "user": "example"
        }

call_id

Type: string

The unique ID of the local shell tool call generated by the model.

Example: example

id

Type: string

The unique ID of the local shell call.

Example: example

status

Type: string

The status of the local shell call.

Enum: in_progress, completed, incomplete

type

Type: string

The type of the local shell call. Always local_shell_call.

Const: local_shell_call

Example: example
Example
{
          "type": "local_shell_call",
          "id": "example",
          "call_id": "example",
          "action": {
            "type": "exec",
            "command": [
              "example"
            ],
            "timeout_ms": 0,
            "working_directory": "example",
            "env": {},
            "user": "example"
          },
          "status": "in_progress"
        }

LocalShellToolCallOutput

The output of a local shell tool call.

Name

Description

id

Type: string

The unique ID of the local shell tool call generated by the model.

Example: example

output

Type: string

A JSON string of the output of the local shell tool call.

Example: example

type

Type: string

The type of the local shell tool call output. Always local_shell_call_output.

Const: local_shell_call_output

Example: example

status
Any of 2 types

  • Type: string

    The status of the item. One of in_progress, completed, or incomplete.

    Enum: in_progress, completed, incomplete

  • Type: null

    Example: null

Example: in_progress
Example
{
          "type": "local_shell_call_output",
          "id": "example",
          "output": "example",
          "status": "in_progress"
        }

FunctionShellAction

Execute a shell command.

Name

Description

commands

Type: string[]

Example
[
          "example"
        ]

max_output_length
Any of 2 types

  • Type: integer

    Optional maximum number of characters to return from each command.

  • Type: null

    Example: null

Example: 0

timeout_ms
Any of 2 types

  • Type: integer

    Optional timeout in milliseconds for the commands.

  • Type: null

    Example: null

Example: 0
Example
{
          "commands": [
            "example"
          ],
          "timeout_ms": 0,
          "max_output_length": 0
        }

LocalEnvironmentResource

Represents the use of a local environment to perform shell actions.

Name

Description

type

Type: string

The environment type. Always local.

Default: local

Const: local
Example
{
          "type": "local"
        }

ContainerReferenceResource

Represents a container created with /v1/containers.

Name

Description

container_id

Type: string

Example: example

type

Type: string

The environment type. Always container_reference.

Default: container_reference

Const: container_reference
Example
{
          "type": "container_reference",
          "container_id": "example"
        }

FunctionShellCall

A tool call that executes one or more shell commands in a managed environment.

Name

Description

action

Type: FunctionShellAction

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

Execute a shell command.

Example
{
          "commands": [
            "example"
          ],
          "timeout_ms": 0,
          "max_output_length": 0
        }

call_id

Type: string

The unique ID of the shell tool call generated by the model.

Example: example

environment
Any of 2 types
  • One of 2 types

    • Local Environment

      Type: LocalEnvironmentResource

      Represents the use of a local environment to perform shell actions.

      Example
      {
          "type": "local"
        }

    • Container Reference

      Type: ContainerReferenceResource

      Represents a container created with /v1/containers.

      Example
      {
          "type": "container_reference",
          "container_id": "example"
        }
    Example
    {
          "type": "local"
        }

  • Type: null

    Example: null

Example
{
          "type": "local"
        }

id

Type: string

The unique ID of the shell tool call. Populated when this item is returned via API.

Example: example

status

Type: LocalShellCallStatus

The status of the shell call. One of in_progress, completed, or incomplete.

Enum: in_progress, completed, incomplete

type

Type: string

The type of the item. Always shell_call.

Default: shell_call

Const: shell_call

created_by

Type: string

The ID of the entity that created this tool call.

Example: example
Example
{
          "type": "shell_call",
          "id": "example",
          "call_id": "example",
          "action": {
            "commands": [
              "example"
            ],
            "timeout_ms": 0,
            "max_output_length": 0
          },
          "status": "in_progress",
          "environment": {
            "type": "local"
          },
          "created_by": "example"
        }

FunctionShellCallOutputTimeoutOutcome

Indicates that the shell call exceeded its configured time limit.

Name

Description

type

Type: string

The outcome type. Always timeout.

Default: timeout

Const: timeout
Example
{
          "type": "timeout"
        }

FunctionShellCallOutputExitOutcome

Indicates that the shell commands finished and returned an exit code.

Name

Description

exit_code

Type: integer

Exit code from the shell process.

type

Type: string

The outcome type. Always exit.

Default: exit

Const: exit
Example
{
          "type": "exit",
          "exit_code": 0
        }

FunctionShellCallOutputContent

The content of a shell tool call output that was emitted.

Name

Description

outcome
One of 2 types

Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.

Example
{
          "type": "timeout"
        }

stderr

Type: string

The standard error output that was captured.

Example: example

stdout

Type: string

The standard output that was captured.

Example: example

created_by

Type: string

The identifier of the actor that created the item.

Example: example
Example
{
          "stdout": "example",
          "stderr": "example",
          "outcome": {
            "type": "timeout"
          },
          "created_by": "example"
        }

FunctionShellCallOutput

The output of a shell tool call that was emitted.

Name

Description

call_id

Type: string

The unique ID of the shell tool call generated by the model.

Example: example

id

Type: string

The unique ID of the shell call output. Populated when this item is returned via API.

Example: example

max_output_length
Any of 2 types

  • Type: integer

    The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output.

  • Type: null

    Example: null

Example: 0

output

Type: FunctionShellCallOutputContent[]

An array of shell call output contents

Example
[
          {
            "stdout": "example",
            "stderr": "example",
            "outcome": {
              "type": "timeout"
            },
            "created_by": "example"
          }
        ]

status

Type: LocalShellCallOutputStatusEnum

The status of the shell call output. One of in_progress, completed, or incomplete.

Enum: in_progress, completed, incomplete

type

Type: string

The type of the shell call output. Always shell_call_output.

Default: shell_call_output

Const: shell_call_output

created_by

Type: string

The identifier of the actor that created the item.

Example: example
Example
{
          "type": "shell_call_output",
          "id": "example",
          "call_id": "example",
          "status": "in_progress",
          "output": [
            {
              "stdout": "example",
              "stderr": "example",
              "outcome": {
                "type": "timeout"
              },
              "created_by": "example"
            }
          ],
          "max_output_length": 0,
          "created_by": "example"
        }

ApplyPatchCallStatus

Type: string

Enum: in_progress, completed

ApplyPatchCreateFileOperation

Instruction describing how to create a file via the apply_patch tool.

Name

Description

diff

Type: string

Diff to apply.

Example: example

path

Type: string

Path of the file to create.

Example: example

type

Type: string

Create a new file with the provided diff.

Default: create_file

Const: create_file
Example
{
          "type": "create_file",
          "path": "example",
          "diff": "example"
        }

ApplyPatchDeleteFileOperation

Instruction describing how to delete a file via the apply_patch tool.

Name

Description

path

Type: string

Path of the file to delete.

Example: example

type

Type: string

Delete the specified file.

Default: delete_file

Const: delete_file
Example
{
          "type": "delete_file",
          "path": "example"
        }

ApplyPatchUpdateFileOperation

Instruction describing how to update a file via the apply_patch tool.

Name

Description

diff

Type: string

Diff to apply.

Example: example

path

Type: string

Path of the file to update.

Example: example

type

Type: string

Update an existing file with the provided diff.

Default: update_file

Const: update_file
Example
{
          "type": "update_file",
          "path": "example",
          "diff": "example"
        }

ApplyPatchToolCall

A tool call that applies file diffs by creating, deleting, or updating files.

Name

Description

call_id

Type: string

The unique ID of the apply patch tool call generated by the model.

Example: example

id

Type: string

The unique ID of the apply patch tool call. Populated when this item is returned via API.

Example: example

operation
One of 3 types

  • Apply patch create file operation

    Type: ApplyPatchCreateFileOperation

    Instruction describing how to create a file via the apply_patch tool.

    Example
    {
          "type": "create_file",
          "path": "example",
          "diff": "example"
        }

  • Apply patch delete file operation

    Type: ApplyPatchDeleteFileOperation

    Instruction describing how to delete a file via the apply_patch tool.

    Example
    {
          "type": "delete_file",
          "path": "example"
        }

  • Apply patch update file operation

    Type: ApplyPatchUpdateFileOperation

    Instruction describing how to update a file via the apply_patch tool.

    Example
    {
          "type": "update_file",
          "path": "example",
          "diff": "example"
        }

One of the create_file, delete_file, or update_file operations applied via apply_patch.

Example
{
          "type": "create_file",
          "path": "example",
          "diff": "example"
        }

status

Type: ApplyPatchCallStatus

The status of the apply patch tool call. One of in_progress or completed.

Enum: in_progress, completed

type

Type: string

The type of the item. Always apply_patch_call.

Default: apply_patch_call

Const: apply_patch_call

created_by

Type: string

The ID of the entity that created this tool call.

Example: example
Example
{
          "type": "apply_patch_call",
          "id": "example",
          "call_id": "example",
          "status": "in_progress",
          "operation": {
            "type": "create_file",
            "path": "example",
            "diff": "example"
          },
          "created_by": "example"
        }

ApplyPatchCallOutputStatus

Type: string

Enum: completed, failed

ApplyPatchToolCallOutput

The output emitted by an apply patch tool call.

Name

Description

call_id

Type: string

The unique ID of the apply patch tool call generated by the model.

Example: example

id

Type: string

The unique ID of the apply patch tool call output. Populated when this item is returned via API.

Example: example

status

Type: ApplyPatchCallOutputStatus

The status of the apply patch tool call output. One of completed or failed.

Enum: completed, failed

type

Type: string

The type of the item. Always apply_patch_call_output.

Default: apply_patch_call_output

Const: apply_patch_call_output

created_by

Type: string

The ID of the entity that created this tool call output.

Example: example

output
Any of 2 types

  • Type: string

    Optional textual output returned by the apply patch tool.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "apply_patch_call_output",
          "id": "example",
          "call_id": "example",
          "status": "completed",
          "output": "example",
          "created_by": "example"
        }

MCPListToolsTool

A tool available on an MCP server.

Name

Description

input_schema

Type: object

The JSON schema describing the tool's input.

Example
{}

name

Type: string

The name of the tool.

Example: example

annotations
Any of 2 types

  • Type: object

    Additional annotations about the tool.

    Example
    {}

  • Type: null

    Example: null

Example
{}

description
Any of 2 types

  • Type: string

    The description of the tool.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "name": "example",
          "description": "example",
          "input_schema": {},
          "annotations": {}
        }

MCPListTools

A list of tools available on an MCP server.

Name

Description

id

Type: string

The unique ID of the list.

Example: example

server_label

Type: string

The label of the MCP server.

Example: example

tools

Type: MCPListToolsTool[]

The tools available on the server.

Example
[
          {
            "name": "example",
            "description": "example",
            "input_schema": {},
            "annotations": {}
          }
        ]

type

Type: string

The type of the item. Always mcp_list_tools.

Const: mcp_list_tools

Example: example

error
Any of 2 types

  • Type: string

    Error message if the server could not list tools.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "mcp_list_tools",
          "id": "example",
          "server_label": "example",
          "tools": [
            {
              "name": "example",
              "description": "example",
              "input_schema": {},
              "annotations": {}
            }
          ],
          "error": "example"
        }

MCPApprovalRequest

A request for human approval of a tool invocation.

Name

Description

arguments

Type: string

A JSON string of arguments for the tool.

Example: example

id

Type: string

The unique ID of the approval request.

Example: example

name

Type: string

The name of the tool to run.

Example: example

server_label

Type: string

The label of the MCP server making the request.

Example: example

type

Type: string

The type of the item. Always mcp_approval_request.

Const: mcp_approval_request

Example: example
Example
{
          "type": "mcp_approval_request",
          "id": "example",
          "server_label": "example",
          "name": "example",
          "arguments": "example"
        }

MCPApprovalResponseResource

A response to an MCP approval request.

Name

Description

approval_request_id

Type: string

The ID of the approval request being answered.

Example: example

approve

Type: boolean

Whether the request was approved.

id

Type: string

The unique ID of the approval response

Example: example

type

Type: string

The type of the item. Always mcp_approval_response.

Const: mcp_approval_response

Example: example

reason
Any of 2 types

  • Type: string

    Optional reason for the decision.

    Example: example

  • Type: null

    Example: null

Example: example
Example
{
          "type": "mcp_approval_response",
          "id": "example",
          "approval_request_id": "example",
          "approve": true,
          "reason": "example"
        }

MCPToolCallStatus

Type: string

Enum: in_progress, completed, incomplete, calling, failed

MCPToolCall

An invocation of a tool on an MCP server.

Name

Description

arguments

Type: string

A JSON string of the arguments passed to the tool.

Example: example

id

Type: string

The unique ID of the tool call.

Example: example

name

Type: string

The name of the tool that was run.

Example: example

server_label

Type: string

The label of the MCP server running the tool.

Example: example

type

Type: string

The type of the item. Always mcp_call.

Const: mcp_call

Example: example

approval_request_id
Any of 2 types

  • Type: string

    Unique identifier for the MCP tool call approval request.
    Include this value in a subsequent mcp_approval_response input to approve or reject the corresponding tool call.

    Example: example

  • Type: null

    Example: null

Example: example

error
Any of 2 types

  • Type: string

    The error from the tool call, if any.

    Example: example

  • Type: null

    Example: null

Example: example

output
Any of 2 types

  • Type: string

    The output from the tool call.

    Example: example

  • Type: null

    Example: null

Example: example

status

Type: MCPToolCallStatus

The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.

Enum: in_progress, completed, incomplete, calling, failed
Example
{
          "type": "mcp_call",
          "id": "example",
          "server_label": "example",
          "name": "example",
          "arguments": "example",
          "output": "example",
          "error": "example",
          "status": "in_progress",
          "approval_request_id": "example"
        }

CustomToolCall

A call to a custom tool created by the model.

Name

Description

call_id

Type: string

An identifier used to map this custom tool call to a tool call output.

Example: example

input

Type: string

The input for the custom tool call generated by the model.

Example: example

name

Type: string

The name of the custom tool being called.

Example: example

type

Type: string

The type of the custom tool call. Always custom_tool_call.

Const: custom_tool_call

Example: example

id

Type: string

The unique ID of the custom tool call in the OpenAI platform.

Example: example

namespace

Type: string

The namespace of the custom tool being called.

Example: example
Example
{
          "type": "custom_tool_call",
          "id": "example",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "input": "example"
        }

CustomToolCallOutput

The output of a custom tool call from your code, being sent back to the model.

Name

Description

call_id

Type: string

The call ID, used to map this custom tool call output to a custom tool call.

Example: example

output
One of: string output or output content list

  • string output

    Type: string

    A string of the output of the custom tool call.

    Example: example

  • output content list

    Type: FunctionAndCustomToolCallOutput[]

    Text, image, or file output of the custom tool call.

    Example
    [
          {
            "type": "input_text",
            "text": "example"
          }
        ]

The output from the custom tool call generated by your code. Can be a string or an list of output content.

Example: example

type

Type: string

The type of the custom tool call output. Always custom_tool_call_output.

Const: custom_tool_call_output

Example: example

id

Type: string

The unique ID of the custom tool call output in the AI Studio platform.

Example: example
Example
{
          "type": "custom_tool_call_output",
          "id": "example",
          "call_id": "example",
          "output": "example"
        }

ConversationItem

A single item within a conversation. The set of possible types are the same as the output type of a Response object.

One of 23 types

  • Message

    Type: Message

    A message to or from the model.

    Example
    {
          "type": "message",
          "id": "example",
          "status": "in_progress",
          "role": "unknown",
          "content": [
            {
              "type": "input_text",
              "text": "example"
            }
          ],
          "phase": "commentary"
        }

  • Type: FunctionToolCallResource

    Example
    {
          "id": "example",
          "type": "function_call",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "arguments": "example",
          "status": "in_progress",
          "created_by": "example"
        }

  • Type: FunctionToolCallOutputResource

    Example
    {
          "id": "example",
          "type": "function_call_output",
          "call_id": "example",
          "output": "example",
          "status": "in_progress",
          "created_by": "example"
        }

  • File search tool call

    Type: FileSearchToolCall

    The results of a File Search tool call.

    Example
    {
          "id": "example",
          "type": "file_search_call",
          "status": "in_progress",
          "queries": [
            "example"
          ],
          "results": [
            {
              "file_id": "example",
              "text": "example",
              "filename": "example",
              "attributes": null,
              "score": 0.5
            }
          ]
        }

  • Web search tool call

    Type: WebSearchToolCall

    The results of a web search tool call.

    Example
    {
          "id": "example",
          "type": "web_search_call",
          "status": "in_progress",
          "action": {
            "type": "search",
            "query": "example",
            "queries": [
              "example"
            ],
            "sources": [
              {
                "type": "url",
                "url": "example"
              }
            ]
          }
        }

  • Image generation call

    Type: ImageGenToolCall

    An image generation request made by the model.

    Example
    {
          "type": "image_generation_call",
          "id": "example",
          "status": "in_progress",
          "result": "example"
        }

  • Type: ToolSearchCall

    Example
    {
          "type": "tool_search_call",
          "id": "example",
          "call_id": "example",
          "execution": "server",
          "arguments": null,
          "status": "in_progress",
          "created_by": "example"
        }

  • Type: ToolSearchOutput

    Example
    {
          "type": "tool_search_output",
          "id": "example",
          "call_id": "example",
          "execution": "server",
          "tools": [
            {
              "type": "function",
              "name": "example",
              "description": "example",
              "parameters": {},
              "strict": true,
              "defer_loading": true
            }
          ],
          "status": "in_progress",
          "created_by": "example"
        }

  • Reasoning

    Type: ReasoningItem

    A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

    Example
    {
          "type": "reasoning",
          "id": "example",
          "encrypted_content": "example",
          "summary": [
            {
              "type": "summary_text",
              "text": "example"
            }
          ],
          "content": [
            {
              "type": "reasoning_text",
              "text": "example"
            }
          ],
          "status": "in_progress"
        }

  • Compaction item

    Type: CompactionBody

    A compaction item generated by the v1/responses/compact API.

    Example
    {
          "type": "compaction",
          "id": "example",
          "encrypted_content": "example",
          "created_by": "example"
        }

  • Code interpreter tool call

    Type: CodeInterpreterToolCall

    A tool call to run code.

    Example
    {
          "type": "code_interpreter_call",
          "id": "example",
          "status": "in_progress",
          "container_id": "example",
          "code": "example",
          "outputs": [
            {
              "type": "logs",
              "logs": "example"
            }
          ]
        }

  • Local shell call

    Type: LocalShellToolCall

    A tool call to run a command on the local shell.

    Example
    {
          "type": "local_shell_call",
          "id": "example",
          "call_id": "example",
          "action": {
            "type": "exec",
            "command": [
              "example"
            ],
            "timeout_ms": 0,
            "working_directory": "example",
            "env": {},
            "user": "example"
          },
          "status": "in_progress"
        }

  • Local shell call output

    Type: LocalShellToolCallOutput

    The output of a local shell tool call.

    Example
    {
          "type": "local_shell_call_output",
          "id": "example",
          "output": "example",
          "status": "in_progress"
        }

  • Shell tool call

    Type: FunctionShellCall

    A tool call that executes one or more shell commands in a managed environment.

    Example
    {
          "type": "shell_call",
          "id": "example",
          "call_id": "example",
          "action": {
            "commands": [
              "example"
            ],
            "timeout_ms": 0,
            "max_output_length": 0
          },
          "status": "in_progress",
          "environment": {
            "type": "local"
          },
          "created_by": "example"
        }

  • Shell call output

    Type: FunctionShellCallOutput

    The output of a shell tool call that was emitted.

    Example
    {
          "type": "shell_call_output",
          "id": "example",
          "call_id": "example",
          "status": "in_progress",
          "output": [
            {
              "stdout": "example",
              "stderr": "example",
              "outcome": {
                "type": "timeout"
              },
              "created_by": "example"
            }
          ],
          "max_output_length": 0,
          "created_by": "example"
        }

  • Apply patch tool call

    Type: ApplyPatchToolCall

    A tool call that applies file diffs by creating, deleting, or updating files.

    Example
    {
          "type": "apply_patch_call",
          "id": "example",
          "call_id": "example",
          "status": "in_progress",
          "operation": {
            "type": "create_file",
            "path": "example",
            "diff": "example"
          },
          "created_by": "example"
        }

  • Apply patch tool call output

    Type: ApplyPatchToolCallOutput

    The output emitted by an apply patch tool call.

    Example
    {
          "type": "apply_patch_call_output",
          "id": "example",
          "call_id": "example",
          "status": "completed",
          "output": "example",
          "created_by": "example"
        }

  • MCP list tools

    Type: MCPListTools

    A list of tools available on an MCP server.

    Example
    {
          "type": "mcp_list_tools",
          "id": "example",
          "server_label": "example",
          "tools": [
            {
              "name": "example",
              "description": "example",
              "input_schema": {},
              "annotations": {}
            }
          ],
          "error": "example"
        }

  • MCP approval request

    Type: MCPApprovalRequest

    A request for human approval of a tool invocation.

    Example
    {
          "type": "mcp_approval_request",
          "id": "example",
          "server_label": "example",
          "name": "example",
          "arguments": "example"
        }

  • MCP approval response

    Type: MCPApprovalResponseResource

    A response to an MCP approval request.

    Example
    {
          "type": "mcp_approval_response",
          "id": "example",
          "approval_request_id": "example",
          "approve": true,
          "reason": "example"
        }

  • MCP tool call

    Type: MCPToolCall

    An invocation of a tool on an MCP server.

    Example
    {
          "type": "mcp_call",
          "id": "example",
          "server_label": "example",
          "name": "example",
          "arguments": "example",
          "output": "example",
          "error": "example",
          "status": "in_progress",
          "approval_request_id": "example"
        }

  • Custom tool call

    Type: CustomToolCall

    A call to a custom tool created by the model.

    Example
    {
          "type": "custom_tool_call",
          "id": "example",
          "call_id": "example",
          "namespace": "example",
          "name": "example",
          "input": "example"
        }

  • Custom tool call output

    Type: CustomToolCallOutput

    The output of a custom tool call from your code, being sent back to the model.

    Example
    {
          "type": "custom_tool_call_output",
          "id": "example",
          "call_id": "example",
          "output": "example"
        }
Example
{
          "type": "message",
          "id": "example",
          "status": "in_progress",
          "role": "unknown",
          "content": [
            {
              "type": "input_text",
              "text": "example"
            }
          ],
          "phase": "commentary"
        }
Предыдущая
Delete a conversation
Следующая
Create items in a conversation