Skip to content
🌕 Lucero

Modifies a run.

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

Authorizations

Parameters

Path Parameters

thread_id
required
string

The ID of the thread that was run.

run_id
required
string

The ID of the run to modify.

Request Body required

object
metadata

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.

object

Responses

200

OK

Represents an execution run on a thread.

object
id
required

The identifier, which can be referenced in API endpoints.

string
object
required

The object type, which is always thread.run.

string
Allowed values: thread.run
created_at
required

The Unix timestamp (in seconds) for when the run was created.

integer
thread_id
required

The ID of the thread that was executed on as a part of this run.

string
assistant_id
required

The ID of the assistant used for execution of this run.

string
status
required

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.

string
Allowed values: queued in_progress requires_action cancelling cancelled failed completed incomplete expired
required_action
required

Details on the action required to continue the run. Will be null if no action is required.

object
type
required

For now, this is always submit_tool_outputs.

string
Allowed values: submit_tool_outputs
submit_tool_outputs
required

Details on the tool outputs needed for this run to continue.

object
tool_calls
required

A list of the relevant tool calls.

Array<object>

Tool call objects

object
id
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.

string
type
required

The type of tool call the output is required for. For now, this is always function.

string
Allowed values: function
function
required

The function definition.

object
name
required

The name of the function.

string
arguments
required

The arguments that the model expects you to pass to the function.

string
last_error
required

The last error associated with this run. Will be null if there are no errors.

object
code
required

One of server_error, rate_limit_exceeded, or invalid_prompt.

string
Allowed values: server_error rate_limit_exceeded invalid_prompt
message
required

A human-readable description of the error.

string
expires_at
required

The Unix timestamp (in seconds) for when the run will expire.

integer
nullable
started_at
required

The Unix timestamp (in seconds) for when the run was started.

integer
nullable
cancelled_at
required

The Unix timestamp (in seconds) for when the run was cancelled.

integer
nullable
failed_at
required

The Unix timestamp (in seconds) for when the run failed.

integer
nullable
completed_at
required

The Unix timestamp (in seconds) for when the run was completed.

integer
nullable
incomplete_details
required

Details on why the run is incomplete. Will be null if the run is not incomplete.

object
reason

The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run.

string
Allowed values: max_completion_tokens max_prompt_tokens
model
required

The model that the assistant used for this run.

string
instructions
required

The instructions that the assistant used for this run.

string
tools
required

The list of tools that the assistant used for this run.

Array
default: <= 20 items
One of:
object
type
required

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
metadata
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.

object
usage
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.).

object
completion_tokens
required

Number of completion tokens used over the course of the run.

integer
prompt_tokens
required

Number of prompt tokens used over the course of the run.

integer
total_tokens
required

Total number of tokens used (prompt + completion).

integer
temperature

The sampling temperature used for this run. If not set, defaults to 1.

number
nullable
top_p

The nucleus sampling value used for this run. If not set, defaults to 1.

number
nullable
max_prompt_tokens
required

The maximum number of prompt tokens specified to have been used over the course of the run.

integer
nullable >= 256
max_completion_tokens
required

The maximum number of completion tokens specified to have been used over the course of the run.

integer
nullable >= 256
truncation_strategy
required

Controls for how a thread will be truncated prior to the run. Use this to control the intial context window of the run.

object
type
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.

string
Allowed values: auto last_messages
last_messages

The number of most recent messages from the thread when constructing the context for the run.

integer
nullable >= 1
tool_choice
required
One of:

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.

string
Allowed values: none auto required
response_format
required
One of:

auto is the default value

string
Allowed values: none auto