POST
/threads/{thread_id}/runs/{run_id}Update run metadata
Updates the metadata attached to a run. Send the key-value pairs you want associated with the run; the metadata object supports up to 16 pairs, with string values and keys of up to 64 characters.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
thread_idstringrequired
The ID of the thread that was run.
run_idstringrequired
The ID of the run to modify.
Metadata to attach to the run.
metadataobjectoptional
Key-value metadata to attach to the run. Supports up to 16 pairs, with keys limited to 64 characters and string values.
200Returns the updated run object, including its current status and metadata.
idstringrequired
The identifier, which can be referenced in API endpoints.
objectstringrequired
The object type, which is always `thread.run`.
created_atintegerrequired
The Unix timestamp (in seconds) for when the run was created.
thread_idstringrequired
The ID of the [thread](https://developers.openai.com/api/docs/assistants/migration) that was executed on as a part of this run.
assistant_idstringrequired
The ID of the [assistant](https://developers.openai.com/api/docs/assistants/migration) used for execution of this run.
statusstringrequired
The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`.
required_actionobjectrequired
Details on the action required to continue the run. Will be `null` if no action is required.
last_errorobjectrequired
The last error associated with this run. Will be `null` if there are no errors.
expires_atintegerrequired
The Unix timestamp (in seconds) for when the run will expire.
started_atintegerrequired
The Unix timestamp (in seconds) for when the run was started.
cancelled_atintegerrequired
The Unix timestamp (in seconds) for when the run was cancelled.
failed_atintegerrequired
The Unix timestamp (in seconds) for when the run failed.
completed_atintegerrequired
The Unix timestamp (in seconds) for when the run was completed.
incomplete_detailsobjectrequired
Details on why the run is incomplete. Will be `null` if the run is not incomplete.
modelstringrequired
The model that the [assistant](https://developers.openai.com/api/docs/assistants/migration) used for this run.
instructionsstringrequired
The instructions that the [assistant](https://developers.openai.com/api/docs/assistants/migration) used for this run.
toolsarray<CodeInterpreterTool>required
The list of tools that the [assistant](https://developers.openai.com/api/docs/assistants/migration) used for this run.
metadataobjectrequired
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, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings
with a maximum length of 512 characters.
usageobjectrequired
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.).
temperaturenumberoptional
The sampling temperature used for this run. If not set, defaults to 1.
top_pnumberoptional
The nucleus sampling value used for this run. If not set, defaults to 1.
max_prompt_tokensintegerrequired
The maximum number of prompt tokens specified to have been used over the course of the run.
max_completion_tokensintegerrequired
The maximum number of completion tokens specified to have been used over the course of the run.
truncation_strategyobjectrequired
Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run.
tool_choicestring | objectrequired
Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and 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.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
parallel_tool_callsbooleanrequired
Whether to enable [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling) during tool use.
response_formatstring | objectrequired
Specifies the format that the model must output. Compatible with [GPT-4o](https://developers.openai.com/api/docs/models/gpt-4o), [GPT-4 Turbo](https://developers.openai.com/api/docs/models/gpt-4-turbo), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
429Returned when the request rate limit is exceeded.
errorobjectrequired
Error handling
A 429 is returned when the request rate limit is exceeded. The thread_id path parameter and run_id path parameter must identify the thread and run to update. metadata supports up to 16 key-value pairs, with keys of at most 64 characters and string values.