Skip to content
Lucero

Create a thread and run it in one request.

POST
/threads/runs

Authorizations

Request Body required

object
assistant_id
required

The ID of the assistant to use to execute this run.

string
thread

If no thread is provided, an empty thread will be created.

object
messages

A list of messages to start the thread with.

Array<object>
object
role
required

The role of the entity that is creating the message. Allowed values include:

  • user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
  • assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.
string
Allowed values: user assistant
content
required
One of:

The text contents of the message.

string
attachments

A list of files attached to the message, and the tools they should be added to.

Array<object>
nullable
object
file_id

The ID of the file to attach to the message.

string
tools

The tools to add this file to.

Array
One of:
object
type
required

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
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 maximum of 512 characters long.

object
tool_resources

A set of resources that are made available to the assistant’s tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

object
code_interpreter
object
file_ids

A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

Array<string>
default: <= 20 items
file_search
One of:
object
vector_store_ids
required

The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread.

Array<string>
<= 1 items
vector_stores

A helper to create a vector store with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread.

Array<object>
<= 1 items
object
file_ids

A list of file IDs to add to the vector store. There can be a maximum of 10000 files in a vector store.

Array<string>
<= 10000 items
chunking_strategy
One of:

The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.

object
type
required

Always auto.

string
Allowed values: auto
metadata

Set of 16 key-value pairs that can be attached to a vector store. This can be useful for storing additional information about the vector store in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

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 maximum of 512 characters long.

object
model
Any of:
string
instructions

Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis.

string
nullable
tools

Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis.

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

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
tool_resources

A set of resources that are used by the assistant’s tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

object
code_interpreter
object
file_ids

A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

Array<string>
default: <= 20 items
file_search
object
vector_store_ids

The ID of the vector store attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.

Array<string>
<= 1 items
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 maximum of 512 characters long.

object
temperature

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.

number
default: 1 nullable <= 2 
1
top_p

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.

number
default: 1 nullable <= 1 
1
stream

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.

boolean
nullable
max_prompt_tokens

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.

integer
nullable >= 256
max_completion_tokens

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.

integer
nullable >= 256
truncation_strategy

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
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
parallel_tool_calls

Whether to enable parallel function calling during tool use.

boolean
default: true
response_format
One of:

auto is the default value

string
Allowed values: auto

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 maximum 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
parallel_tool_calls
required

Whether to enable parallel function calling during tool use.

boolean
default: true
response_format
required
One of:

auto is the default value

string
Allowed values: auto