--- title: "Returns a list of runs belonging to a thread." method: GET path: "/threads/{thread_id}/runs" tags: ["Assistants"] --- # Returns a list of runs belonging to a thread. `GET /threads/{thread_id}/runs` ## Path parameters - `thread_id` string, required ## Query parameters - `limit` integer - `order` 'asc' | 'desc' - `after` string - `before` string ## Response `200` OK - ListRunsResponse - `object` string, required - `data` RunObject[], required - `id` string, required — The identifier, which can be referenced in API endpoints. - `object` 'thread.run', required — The object type, which is always `thread.run`. - `created_at` integer, required — The Unix timestamp (in seconds) for when the run was created. - `thread_id` string, required — The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - `assistant_id` string, required — The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - `status` 'queued' | 'in_progress' | 'requires_action' | 'cancelling' | 'cancelled' | 'failed' | 'completed' | 'incomplete' | 'expired', required — The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - `required_action` object, nullable, required — Details on the action required to continue the run. Will be `null` if no action is required. - `type` 'submit_tool_outputs', required — For now, this is always `submit_tool_outputs`. - `submit_tool_outputs` object, required — Details on the tool outputs needed for this run to continue. - `tool_calls` RunToolCallObject[], required — A list of the relevant tool calls. - `id` string, 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](/docs/api-reference/runs/submitToolOutputs) endpoint. - `type` 'function', required — The type of tool call the output is required for. For now, this is always `function`. - `function` object, required — The function definition. - `name` string, required — The name of the function. - `arguments` string, required — The arguments that the model expects you to pass to the function. - `last_error` object, nullable, required — The last error associated with this run. Will be `null` if there are no errors. - `code` 'server_error' | 'rate_limit_exceeded' | 'invalid_prompt', required — One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - `message` string, required — A human-readable description of the error. - `expires_at` integer, nullable, required — The Unix timestamp (in seconds) for when the run will expire. - `started_at` integer, nullable, required — The Unix timestamp (in seconds) for when the run was started. - `cancelled_at` integer, nullable, required — The Unix timestamp (in seconds) for when the run was cancelled. - `failed_at` integer, nullable, required — The Unix timestamp (in seconds) for when the run failed. - `completed_at` integer, nullable, required — The Unix timestamp (in seconds) for when the run was completed. - `incomplete_details` object, nullable, required — Details on why the run is incomplete. Will be `null` if the run is not incomplete. - `reason` 'max_completion_tokens' | 'max_prompt_tokens' — The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - `model` string, required — The model that the [assistant](/docs/api-reference/assistants) used for this run. - `instructions` string, required — The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - `tools` union[], required — The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - union - AssistantToolsCode - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter` - AssistantToolsFileSearch - `type` 'file_search', required — The type of tool being defined: `file_search` - `file_search` object — Overrides for the file search tool. - `max_num_results` integer — The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - `ranking_options` FileSearchRankingOptions — The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - … - AssistantToolsFunction - `type` 'function', required — The type of tool being defined: `function` - `function` FunctionObject, required - `description` string — A description of what the function does, used by the model to choose when and how to call the function. - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list. - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - `metadata` Metadata, nullable, 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, 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. - `usage` RunCompletionUsage, nullable, 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.). - `completion_tokens` integer, required — Number of completion tokens used over the course of the run. - `prompt_tokens` integer, required — Number of prompt tokens used over the course of the run. - `total_tokens` integer, required — Total number of tokens used (prompt + completion). - `temperature` number, nullable — The sampling temperature used for this run. If not set, defaults to 1. - `top_p` number, nullable — The nucleus sampling value used for this run. If not set, defaults to 1. - `max_prompt_tokens` integer, nullable, required — The maximum number of prompt tokens specified to have been used over the course of the run. - `max_completion_tokens` integer, nullable, required — The maximum number of completion tokens specified to have been used over the course of the run. - `truncation_strategy` object, nullable, required — Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - `type` 'auto' | 'last_messages', 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`. - `last_messages` integer, nullable — The number of most recent messages from the thread when constructing the context for the run. - `tool_choice` union, required - 'none' | 'auto' | 'required', nullable — `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. - object, nullable — Specifies a tool the model should use. Use to force the model to call a specific tool. - `type` 'function' | 'code_interpreter' | 'file_search', required — The type of the tool. If type is `function`, the function name must be set - `function` object - `name` string, required — The name of the function to call. - `parallel_tool_calls` boolean, required — Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - `response_format` union, required — Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), 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](/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. - 'auto' — `auto` is the default value - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - ResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/docs/guides/structured-outputs). - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `json_schema` object, required — Structured Outputs configuration options, including a JSON Schema. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` ResponseFormatJsonSchemaSchema — The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](/docs/guides/structured-outputs). - `first_id` string, required - `last_id` string, required - `has_more` boolean, required --- [API](https://skmtc.net/openai/apis/openai-api-3.md) · [All operations](https://skmtc.net/openai/apis/openai-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openai/openai-api-3/versions/74cbcf73838f/schema)