OpenAI API (unofficial showcase)
POST/threads/{thread_id}/runs

Create a run on a thread

Creates a run on a thread using the specified assistant. Supply assistant_id and optionally override the assistant’s model, instructions, tools, or generation settings for this run. If the run requires tool outputs, submit them with POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 17 body fields
thread_idstringrequired
The ID 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 the assistant. assistant_id is required; other fields customize the run.

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_messagesarrayoptional
Adds additional messages to the thread before creating the run.
toolsarrayoptional
Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis.
metadataobjectoptional
Key-value metadata to attach to the run. Supports up to 16 pairs, with keys limited to 64 characters and string values.
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.
tool_choiceobjectoptional
Controls whether the model can choose tools or must or must not call them.
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 run object, including its ID, thread and assistant IDs, status, timestamps, model, and any required action or last error.
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
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.
Default:true
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 must identify the thread to run, and assistant_id is required. reasoning_effort must be one of none, minimal, low, medium, high, xhigh, or max; temperature must be between 0 and 2, top_p between 0 and 1, and each token limit must be at least 256.