Retrieves a run.

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

Copy endpoint

https://api.openai.com/v1

Parameters

path Path Parameters

Name	Type
`thread_id` required The ID of the thread that was run.	string
`run_id` required The ID of the run to retrieve.	string

Responses

200 application/json

interface RunObject {
id: string;
object: "thread.run";
created_at: number;
thread_id: string;
assistant_id: string;
status: "queued" | "in_progress" | "requires_action" | "cancelling" | "cancelled" | "failed" | "completed" | "incomplete" | "expired";
required_action: { type: "submit_tool_outputs";submit_tool_outputs: { tool_calls:

RunToolCallObject

Tool call objects

interface RunToolCallObject {
id: string;
type: "function";
function: { name: string;arguments: string; };
}

[]; }; } | null;
last_error: { code: "server_error" | "rate_limit_exceeded" | "invalid_prompt";message: string; } | null;
expires_at: number | null;
started_at: number | null;
cancelled_at: number | null;
failed_at: number | null;
completed_at: number | null;
incomplete_details: { reason?: "max_completion_tokens" | "max_prompt_tokens"; } | null;
model: string;
instructions: string;
tools: (

AssistantToolsCode

interface AssistantToolsCode {
type: "code_interpreter";
}

AssistantToolsFileSearch

interface AssistantToolsFileSearch {
type: "file_search";
file_search?: { max_num_results?: number;ranking_options?: FileSearchRankingOptions; };
}

AssistantToolsFunction

interface AssistantToolsFunction {
type: "function";
function: FunctionObject;
}

)[];
metadata:

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, 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.

type Metadata = { } | null

;
usage:

RunCompletionUsage

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.).

type RunCompletionUsage = { completion_tokens: number;prompt_tokens: number;total_tokens: number; } | null

;
temperature?: number | null;
top_p?: number | null;
max_prompt_tokens: number | null;
max_completion_tokens: number | null;
truncation_strategy:

TruncationObject

Controls for how a thread will be truncated prior to the run. Use this to control the intial context window of the run.

interface TruncationObject {
type: "auto" | "last_messages";
last_messages?: number | null;
}

& null;
tool_choice:

AssistantsApiToolChoiceOption

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.

type AssistantsApiToolChoiceOption = AssistantsNamedToolChoice | "none" | "auto" | "required"

& null;
parallel_tool_calls:

ParallelToolCalls

Whether to enable parallel function calling during tool use.

type ParallelToolCalls = boolean

;
response_format:

AssistantsApiResponseFormatOption

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.

type AssistantsApiResponseFormatOption = ResponseFormatText | ResponseFormatJsonObject | ResponseFormatJsonSchema | "auto"

;
}