Submit tool outputs to run

POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs

When a run has the status: "requires_action" and required_action.type is submit_tool_outputs, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request.

Path parameters

thread_id string Required

The ID of the thread to which this run belongs.
run_id string Required

The ID of the run that requires the tool output submission.

application/json

Body Required

tool_outputs array[object] Required

A list of tools for which the outputs are being submitted.
Hide tool_outputs attributes Show tool_outputs attributes object
- tool_call_id string
  
  The ID of the tool call in the required_action object within the run object the output is being submitted for.
- output string
  
  The output of the tool call to be submitted to continue the run.
stream boolean | null

If true, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a data: [DONE] message.
Additional properties are NOT allowed

Responses

200 application/json

OK
Hide response attributes Show response attributes object
- id string Required
  
  The identifier, which can be referenced in API endpoints.
- object string Required
  
  The object type, which is always thread.run.
  
  Value is thread.run.
- created_at integer Required
  
  The Unix timestamp (in seconds) for when the run was created.
- thread_id string Required
  
  The ID of the thread that was executed on as a part of this run.
- assistant_id string Required
  
  The ID of the assistant used for execution of this run.
- status string Required
  
  The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.
  
  Values are queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.
- required_action object | null Required
  
  Details on the action required to continue the run. Will be null if no action is required.
  
  Hide required_action attributes Show required_action attributes object | null
  
  type string Required
  
  For now, this is always submit_tool_outputs.
  
  Value is submit_tool_outputs.
  
  submit_tool_outputs object Required
  
  Details on the tool outputs needed for this run to continue.
  
  Hide submit_tool_outputs attribute Show submit_tool_outputs attribute object
  
  tool_calls array[object] Required
  
  Tool call objects
  
  Hide tool_calls attributes Show tool_calls attributes object
  
  id string Required
  
  The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the Submit tool outputs to run endpoint.
  
  type string Required
  
  The type of tool call the output is required for. For now, this is always function.
  
  Value is function.
  
  function object Required
  
  The function definition.
  
  Hide function attributes Show function attributes object
  
  name string Required
  
  The name of the function.
  
  arguments string Required
  
  The arguments that the model expects you to pass to the function.
- last_error object | null Required
  
  The last error associated with this run. Will be null if there are no errors.
  
  Hide last_error attributes Show last_error attributes object | null
  
  code string Required
  
  One of server_error, rate_limit_exceeded, or invalid_prompt.
  
  Values are server_error, rate_limit_exceeded, or invalid_prompt.
  
  message string Required
  
  A human-readable description of the error.
- expires_at integer | null Required
  
  The Unix timestamp (in seconds) for when the run will expire.
- started_at integer | null Required
  
  The Unix timestamp (in seconds) for when the run was started.
- cancelled_at integer | null Required
  
  The Unix timestamp (in seconds) for when the run was cancelled.
- failed_at integer | null Required
  
  The Unix timestamp (in seconds) for when the run failed.
- completed_at integer | null Required
  
  The Unix timestamp (in seconds) for when the run was completed.
- incomplete_details object | null Required
  
  Details on why the run is incomplete. Will be null if the run is not incomplete.
  
  Hide incomplete_details attribute Show incomplete_details attribute object | null
  
  reason string
  
  The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run.
  
  Values are max_completion_tokens or max_prompt_tokens.
- model string Required
  
  The model that the assistant used for this run.
- instructions string Required
  
  The instructions that the assistant used for this run.
- tools array[object] Required
  
  The list of tools that the assistant used for this run.
  
  Not more than 20 elements. Default value is [] (empty).
  
  One of:
  Code interpreter tool object FileSearch tool object Function tool object
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of tool being defined: file_search
  
  Value is file_search.
  
  file_search object
  
  Overrides for the file search tool.
  
  Hide file_search attribute Show file_search attribute object
  
  max_num_results integer
  
  The maximum number of results the file search tool should output. The default is 20 for gpt-4* models and 5 for gpt-3.5-turbo. This number should be between 1 and 50 inclusive.
  
  Note that the file search tool may output fewer than max_num_results results. See the file search tool documentation for more information.
  
  Minimum value is 1, maximum value is 50.
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of tool being defined: function
  
  Value is function.
  
  function object Required
  
  Hide function attributes Show function attributes object
  
  description string
  
  A description of what the function does, used by the model to choose when and how to call the function.
  
  name string Required
  
  The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
  
  parameters object
  
  The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.
  
  Omitting parameters defines a function with an empty parameter list.
  
  Hide parameters attribute Show parameters attribute object
  
  Additional properties are allowed
- metadata object | null Required
  
  Set of 16 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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.
- usage object | null Required
  
  Usage statistics related to the run. This value will be null if the run is not in a terminal state (i.e. in_progress, queued, etc.).
  
  Hide usage attributes Show usage attributes object | null
  
  completion_tokens integer Required
  
  Number of completion tokens used over the course of the run.
  
  prompt_tokens integer Required
  
  Number of prompt tokens used over the course of the run.
  
  total_tokens integer Required
  
  Total number of tokens used (prompt + completion).
- temperature number | null
  
  The sampling temperature used for this run. If not set, defaults to 1.
- top_p number | null
  
  The nucleus sampling value used for this run. If not set, defaults to 1.
- max_prompt_tokens integer | null Required
  
  The maximum number of prompt tokens specified to have been used over the course of the run.
  
  Minimum value is 256.
- max_completion_tokens integer | null Required
  
  The maximum number of completion tokens specified to have been used over the course of the run.
  
  Minimum value is 256.
- truncation_strategy object | null Required
  
  Controls for how a thread will be truncated prior to the run. Use this to control the intial context window of the run.
  
  Hide truncation_strategy attributes Show truncation_strategy attributes object | null
  
  type string Required
  
  The truncation strategy to use for the thread. The default is auto. If set to last_messages, the thread will be truncated to the n most recent messages in the thread. When set to auto, messages in the middle of the thread will be dropped to fit the context length of the model, max_prompt_tokens.
  
  Values are auto or last_messages.
  
  last_messages integer | null
  
  The number of most recent messages from the thread when constructing the context for the run.
  
  Minimum value is 1.
- tool_choice string | null | object Required
  
  One of:
  string-1 string | null AssistantsNamedToolChoice object | null
  
  none means the model will not call any tools and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools before responding to the user.
  
  Values are none, auto, or required.
  
  Specifies a tool the model should use. Use to force the model to call a specific tool.
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of the tool. If type is function, the function name must be set
  
  Values are function, code_interpreter, or file_search.
  
  function object
  
  Hide function attribute Show function attribute object
  
  name string Required
  
  The name of the function to call.
- response_format string | null | object Required
  
  One of:
  string-1 string | null AssistantsApiResponseFormat object | null
  
  auto is the default value
  
  Values are none or auto.
  
  An object describing the expected output of the model. If json_object only function type tools are allowed to be passed to the Run. If text the model can return text or any value needed.
  
  Hide attribute Show attribute
  
  type string
  
  Must be one of text or json_object.
  
  Values are text or json_object. Default value is text.

POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs

curl \
 -X POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"tool_outputs":[{"tool_call_id":"string","output":"string"}],"stream":true}'

Request example

{
  "tool_outputs": [
    {
      "tool_call_id": "string",
      "output": "string"
    }
  ],
  "stream": true
}

Response examples (200)

{
  "id": "string",
  "object": "thread.run",
  "created_at": 42,
  "thread_id": "string",
  "assistant_id": "string",
  "status": "queued",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "string",
          "type": "function",
          "function": {
            "name": "string",
            "arguments": "string"
          }
        }
      ]
    }
  },
  "last_error": {
    "code": "server_error",
    "message": "string"
  },
  "expires_at": 42,
  "started_at": 42,
  "cancelled_at": 42,
  "failed_at": 42,
  "completed_at": 42,
  "incomplete_details": {
    "reason": "max_completion_tokens"
  },
  "model": "string",
  "instructions": "string",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": {
    "completion_tokens": 42,
    "prompt_tokens": 42,
    "total_tokens": 42
  },
  "temperature": 42.0,
  "top_p": 42.0,
  "max_prompt_tokens": 42,
  "max_completion_tokens": 42,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": 42
  },
  "tool_choice": "none",
  "response_format": "none"
}

Submit tool outputs to run

Path parameters

Body Required

Responses

tool_choice string | null | object Required

response_format string | null | object Required