Sample - OpenAI API
POST/threads/{thread_id}/runs/{run_id}

Modify a thread run

Updates the metadata associated with a run on a thread. Send metadata to replace the run's metadata values, or provide null to clear the metadata.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 1 body field
thread_idstringrequired
The identifier of the thread on which the run was executed.
run_idstringrequired
The identifier of the run to modify.

Run metadata update payload.

metadataobjectoptional
Metadata to associate with the run as string key-value pairs, or `null` to clear the metadata.

2 status codes
200Returns the updated run object with its current metadata and execution state.
idstringrequired
The identifier, which can be referenced in API endpoints.
objectstringrequired
The object type, which is always `thread.run`.
Allowed: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`.
Allowed:queuedin_progressrequires_actioncancellingcancelledfailedcompletedincompleteexpired
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.
Default:[]
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
tool_choiceobjectrequired
parallel_tool_callsbooleanrequired
Whether to enable [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling) during tool use.
Default:true
response_formatstringrequired
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.
Allowed:auto
429Returned when the request was rejected because a rate limit was exceeded.
errorobjectrequired

Error handling

A 429 is returned when the request exceeds the rate limit. thread_id and run_id must identify the run to modify, and metadata must be an object of string key-value pairs or null when supplied.