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

Create a run for a thread

Creates a run that executes an assistant against a thread. Supply assistant_id and optionally override the model, instructions, tools, sampling controls, token limits, or stream behaviour for the run.

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

2 parameters · 17 body fields
thread_idstringrequired
The identifier of the thread to run.
include[]array<string>optional
Additional response fields to include; the supported value is `step_details.tool_calls[*].file_search.results[*].content`.

Run configuration for executing an assistant against the thread.

assistant_idstringrequired
The ID of the [assistant](https://developers.openai.com/api/docs/assistants/migration) to use to execute this run.
modelstringoptional
The ID of the [Model](https://developers.openai.com/api/reference/resources/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used.
reasoning_effortstringoptional
Reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Defaults to `medium` when omitted.
Allowed:noneminimallowmediumhighxhighmaxDefault:medium
instructionsstringoptional
Overrides the [instructions](https://developers.openai.com/api/docs/assistants/migration) of the assistant. This is useful for modifying the behavior on a per-run basis.
additional_instructionsstringoptional
Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions.
additional_messagesarray<object>optional
Adds additional messages to the thread before creating the run.
toolsarray<CodeInterpreterTool>optional
Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis.
metadataobjectoptional
String key-value pairs attached to the run; keys can be up to 64 characters, with up to 16 pairs, or `null`.
temperaturenumberoptional
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
Default:1
top_pnumberoptional
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
Default:1
streambooleanoptional
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.
max_prompt_tokensintegeroptional
The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
max_completion_tokensintegeroptional
The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info.
truncation_strategyobjectoptional
Controls how the thread is truncated before the run, including the truncation type and optional last-message setting.
tool_choiceobjectoptional
Controls whether the model avoids tools, selects tools automatically, or must call a tool.
parallel_tool_callsbooleanoptional
Whether to enable [parallel function calling](https://developers.openai.com/api/docs/guides/function-calling#parallel-function-calling) during tool use.
Default:true
response_formatstringoptional
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

2 status codes
200Returns the created run object with its identifier, thread and assistant associations, status, model, timestamps, required action, errors, and instructions.
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. assistant_id is required, include[] only accepts step_details.tool_calls[*].file_search.results[*].content, temperature must be between 0 and 2, and top_p must be between 0 and 1. max_prompt_tokens and max_completion_tokens must each be at least 256 when provided.