API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Threads

Build Assistants that can call models and use tools.

Create thread

Deprecated

beta.threads.create(ThreadCreateParams**kwargs) -> Thread

POST/threads

Create thread and run

Deprecated

beta.threads.create_and_run(ThreadCreateAndRunParams**kwargs) -> Run

POST/threads/runs

Delete thread

Deprecated

beta.threads.delete(strthread_id) -> ThreadDeleted

DELETE/threads/{thread_id}

Retrieve thread

Deprecated

beta.threads.retrieve(strthread_id) -> Thread

GET/threads/{thread_id}

Modify thread

Deprecated

beta.threads.update(strthread_id, ThreadUpdateParams**kwargs) -> Thread

POST/threads/{thread_id}

ModelsExpand Collapse

AssistantResponseFormatOption

Specifies the format that the model must output. Compatible with GPT-4o, 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.

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.

class AssistantToolChoice: …

Specifies a tool the model should use. Use to force the model to call a specific tool.

class AssistantToolChoiceFunction: …

AssistantToolChoiceOption

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.

class Thread: …

Represents a thread that contains messages.

class ThreadDeleted: …

ThreadsMessages

Build Assistants that can call models and use tools.

Create message

Deprecated

beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message

POST/threads/{thread_id}/messages

Delete message

Deprecated

beta.threads.messages.delete(strmessage_id, MessageDeleteParams**kwargs) -> MessageDeleted

DELETE/threads/{thread_id}/messages/{message_id}

List messages

Deprecated

beta.threads.messages.list(strthread_id, MessageListParams**kwargs) -> SyncCursorPage[Message]

GET/threads/{thread_id}/messages

Retrieve message

Deprecated

beta.threads.messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message

GET/threads/{thread_id}/messages/{message_id}

Modify message

Deprecated

beta.threads.messages.update(strmessage_id, MessageUpdateParams**kwargs) -> Message

POST/threads/{thread_id}/messages/{message_id}

ModelsExpand Collapse

Annotation

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.

AnnotationDelta

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.

class FileCitationAnnotation: …

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.

class FileCitationDeltaAnnotation: …

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.

class FilePathAnnotation: …

A URL for the file that’s generated when the assistant used the code_interpreter tool to generate a file.

class FilePathDeltaAnnotation: …

A URL for the file that’s generated when the assistant used the code_interpreter tool to generate a file.

class ImageFile: …

class ImageFileContentBlock: …

References an image File in the content of a message.

class ImageFileDelta: …

class ImageFileDeltaBlock: …

References an image File in the content of a message.

class ImageURL: …

class ImageURLContentBlock: …

References an image URL in the content of a message.

class ImageURLDelta: …

class ImageURLDeltaBlock: …

References an image URL in the content of a message.

class Message: …

Represents a message within a thread.

MessageContent

References an image File in the content of a message.

MessageContentDelta

References an image File in the content of a message.

MessageContentPartParam

References an image File in the content of a message.

class MessageDeleted: …

class MessageDelta: …

The delta containing the fields that have changed on the Message.

class MessageDeltaEvent: …

Represents a message delta i.e. any changed fields on a message during streaming.

class RefusalContentBlock: …

The refusal content generated by the assistant.

class RefusalDeltaBlock: …

The refusal content that is part of a message.

class Text: …

class TextContentBlock: …

The text content that is part of a message.

class TextContentBlockParam: …

The text content that is part of a message.

class TextDelta: …

class TextDeltaBlock: …

The text content that is part of a message.

ThreadsRuns

Build Assistants that can call models and use tools.

Cancel a run

Deprecated

beta.threads.runs.cancel(strrun_id, RunCancelParams**kwargs) -> Run

POST/threads/{thread_id}/runs/{run_id}/cancel

Create run

Deprecated

beta.threads.runs.create(strthread_id, RunCreateParams**kwargs) -> Run

POST/threads/{thread_id}/runs

List runs

Deprecated

beta.threads.runs.list(strthread_id, RunListParams**kwargs) -> SyncCursorPage[Run]

GET/threads/{thread_id}/runs

Retrieve run

Deprecated

beta.threads.runs.retrieve(strrun_id, RunRetrieveParams**kwargs) -> Run

GET/threads/{thread_id}/runs/{run_id}

Submit tool outputs to run

Deprecated

beta.threads.runs.submit_tool_outputs(strrun_id, RunSubmitToolOutputsParams**kwargs) -> Run

POST/threads/{thread_id}/runs/{run_id}/submit_tool_outputs

Modify run

Deprecated

beta.threads.runs.update(strrun_id, RunUpdateParams**kwargs) -> Run

POST/threads/{thread_id}/runs/{run_id}

ModelsExpand Collapse

class RequiredActionFunctionToolCall: …

Tool call objects

class Run: …

Represents an execution run on a thread.

Literal["queued", "in_progress", "requires_action", 6 more]

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.

ThreadsRunsSteps

Build Assistants that can call models and use tools.

List run steps

Deprecated

beta.threads.runs.steps.list(strrun_id, StepListParams**kwargs) -> SyncCursorPage[RunStep]

GET/threads/{thread_id}/runs/{run_id}/steps

Retrieve run step

Deprecated

beta.threads.runs.steps.retrieve(strstep_id, StepRetrieveParams**kwargs) -> RunStep

GET/threads/{thread_id}/runs/{run_id}/steps/{step_id}

ModelsExpand Collapse

class CodeInterpreterLogs: …

Text output from the Code Interpreter tool call as part of a run step.

class CodeInterpreterOutputImage: …

class CodeInterpreterToolCall: …

Details of the Code Interpreter tool call the run step was involved in.

class CodeInterpreterToolCallDelta: …

Details of the Code Interpreter tool call the run step was involved in.

class FileSearchToolCall: …

class FileSearchToolCallDelta: …

class FunctionToolCall: …

class FunctionToolCallDelta: …

class MessageCreationStepDetails: …

Details of the message creation by the run step.

class RunStep: …

Represents a step in execution of a run.

class RunStepDelta: …

The delta containing the fields that have changed on the run step.

class RunStepDeltaEvent: …

Represents a run step delta i.e. any changed fields on a run step during streaming.

class RunStepDeltaMessageDelta: …

Details of the message creation by the run step.

Literal["step_details.tool_calls[*].file_search.results[*].content"]

ToolCall

Details of the Code Interpreter tool call the run step was involved in.

ToolCallDelta

Details of the Code Interpreter tool call the run step was involved in.

class ToolCallDeltaObject: …

Details of the tool call.

class ToolCallsStepDetails: …

Details of the tool call.