diff --git a/en/resources/beta/subresources/threads/index.md b/en/resources/beta/subresources/threads/index.md index 7c15656e..d2dfe6a0 100644 --- a/en/resources/beta/subresources/threads/index.md +++ b/en/resources/beta/subresources/threads/index.md @@ -171,7 +171,7 @@ Create a thread. The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `AutoChunkingStrategy object { type }` + - `Auto object { type }` The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. @@ -181,7 +181,7 @@ Create a thread. - `"auto"` - - `StaticChunkingStrategy object { static, type }` + - `Static object { static, type }` - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` @@ -721,7 +721,7 @@ Create a thread and run it in one request. The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `AutoChunkingStrategy object { type }` + - `Auto object { type }` The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. @@ -731,7 +731,7 @@ Create a thread and run it in one request. - `"auto"` - - `StaticChunkingStrategy object { static, type }` + - `Static object { static, type }` - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` @@ -1600,6 +1600,67 @@ event: done data: [DONE] ``` +## Delete thread + +**delete** `/threads/{thread_id}` + +Delete a thread. + +### Path Parameters + +- `thread_id: string` + +### Returns + +- `ThreadDeleted object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "thread.deleted"` + + - `"thread.deleted"` + +### Example + +```http +curl https://api.openai.com/v1/threads/$THREAD_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE +``` + +#### Response + +```json +{ + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true +} +``` + ## Retrieve thread **get** `/threads/{thread_id}` @@ -1860,67 +1921,6 @@ curl https://api.openai.com/v1/threads/thread_abc123 \ } ``` -## Delete thread - -**delete** `/threads/{thread_id}` - -Delete a thread. - -### Path Parameters - -- `thread_id: string` - -### Returns - -- `ThreadDeleted object { id, deleted, object }` - - - `id: string` - - - `deleted: boolean` - - - `object: "thread.deleted"` - - - `"thread.deleted"` - -### Example - -```http -curl https://api.openai.com/v1/threads/$THREAD_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` - -#### Response - -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` - -### Example - -```http -curl https://api.openai.com/v1/threads/thread_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -X DELETE -``` - -#### Response - -```json -{ - "id": "thread_abc123", - "object": "thread.deleted", - "deleted": true -} -``` - ## Domain Types ### Assistant Response Format Option @@ -2129,450 +2129,515 @@ curl https://api.openai.com/v1/threads/thread_abc123 \ - `"thread.deleted"` -# Runs +# Messages -## List runs +## Create message -**get** `/threads/{thread_id}/runs` +**post** `/threads/{thread_id}/messages` -Returns a list of runs belonging to a thread. +Create a message. ### Path Parameters - `thread_id: string` -### Query Parameters - -- `after: optional string` +### Body Parameters - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. +- `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` -- `before: optional string` + The text contents of the message. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `TextContent = string` -- `limit: optional number` + The text contents of the message. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` -- `order: optional "asc" or "desc"` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `ImageFileContentBlock object { image_file, type }` - - `"asc"` + References an image [File](/docs/api-reference/files) in the content of a message. - - `"desc"` + - `image_file: ImageFile` -### Returns + - `file_id: string` -- `data: array of Run` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `id: string` + - `detail: optional "auto" or "low" or "high"` - The identifier, which can be referenced in API endpoints. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `assistant_id: string` + - `"auto"` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `"low"` - - `cancelled_at: number` + - `"high"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `type: "image_file"` - - `completed_at: number` + Always `image_file`. - The Unix timestamp (in seconds) for when the run was completed. + - `"image_file"` - - `created_at: number` + - `ImageURLContentBlock object { image_url, type }` - The Unix timestamp (in seconds) for when the run was created. + References an image URL in the content of a message. - - `expires_at: number` + - `image_url: ImageURL` - The Unix timestamp (in seconds) for when the run will expire. + - `url: string` - - `failed_at: number` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The Unix timestamp (in seconds) for when the run failed. + - `detail: optional "auto" or "low" or "high"` - - `incomplete_details: object { reason }` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `"auto"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"low"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"high"` - - `"max_completion_tokens"` + - `type: "image_url"` - - `"max_prompt_tokens"` + The type of the content part. - - `instructions: string` + - `"image_url"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `TextContentBlockParam object { text, type }` - - `last_error: object { code, message }` + The text content that is part of a message. - The last error associated with this run. Will be `null` if there are no errors. + - `text: string` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + Text content to be sent to the model - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "text"` - - `"server_error"` + Always `text`. - - `"rate_limit_exceeded"` + - `"text"` - - `"invalid_prompt"` +- `role: "user" or "assistant"` - - `message: string` + The role of the entity that is creating the message. Allowed values include: - A human-readable description of the error. + - `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. - - `max_completion_tokens: number` + - `"user"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"assistant"` - - `max_prompt_tokens: number` +- `attachments: optional array of object { file_id, tools }` - The maximum number of prompt tokens specified to have been used over the course of the run. + A list of files attached to the message, and the tools they should be added to. - - `metadata: Metadata` + - `file_id: optional string` - 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. + The ID of the file to attach to the message. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `model: string` + The tools to add this file to. - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `CodeInterpreterTool object { type }` - - `object: "thread.run"` + - `type: "code_interpreter"` - The object type, which is always `thread.run`. + The type of tool being defined: `code_interpreter` - - `"thread.run"` + - `"code_interpreter"` - - `parallel_tool_calls: boolean` + - `FileSearchTool object { type }` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `type: "file_search"` - - `required_action: object { submit_tool_outputs, type }` + The type of tool being defined: `file_search` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"file_search"` - - `submit_tool_outputs: object { tool_calls }` +- `metadata: optional Metadata` - Details on the tool outputs needed for this run to continue. + 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. - - `tool_calls: array of RequiredActionFunctionToolCall` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A list of the relevant tool calls. +### Returns - - `id: string` +- `Message object { id, assistant_id, attachments, 11 more }` - 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. + Represents a message within a [thread](/docs/api-reference/threads). - - `function: object { arguments, name }` + - `id: string` - The function definition. + The identifier, which can be referenced in API endpoints. - - `arguments: string` + - `assistant_id: string` - The arguments that the model expects you to pass to the function. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `name: string` + - `attachments: array of object { file_id, tools }` - The name of the function. + A list of files attached to the message, and the tools they were added to. - - `type: "function"` + - `file_id: optional string` - The type of tool call the output is required for. For now, this is always `function`. + The ID of the file to attach to the message. - - `"function"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `type: "submit_tool_outputs"` + The tools to add this file to. - For now, this is always `submit_tool_outputs`. + - `CodeInterpreterTool object { type }` - - `"submit_tool_outputs"` + - `type: "code_interpreter"` - - `response_format: AssistantResponseFormatOption` + The type of tool being defined: `code_interpreter` - 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`. + - `"code_interpreter"` - 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). + - `FileSearchTool object { type }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `type: "file_search"` - **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. + The type of tool being defined: `file_search` - - `"auto"` + - `"file_search"` - `auto` is the default value + - `completed_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the message was completed. - - `ResponseFormatText object { type }` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - Default response format. Used to generate text responses. + The content of the message in array of text and/or images. - - `type: "text"` + - `ImageFileContentBlock object { image_file, type }` - The type of response format being defined. Always `text`. + References an image [File](/docs/api-reference/files) in the content of a message. - - `"text"` + - `image_file: ImageFile` - - `ResponseFormatJSONObject object { type }` + - `file_id: string` - 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. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `type: "json_object"` + - `detail: optional "auto" or "low" or "high"` - The type of response format being defined. Always `json_object`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"json_object"` + - `"auto"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"low"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `"high"` - - `json_schema: object { name, description, schema, strict }` + - `type: "image_file"` - Structured Outputs configuration options, including a JSON Schema. + Always `image_file`. - - `name: string` + - `"image_file"` - 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. + - `ImageURLContentBlock object { image_url, type }` - - `description: optional string` + References an image URL in the content of a message. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `image_url: ImageURL` - - `schema: optional map[unknown]` + - `url: string` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `strict: optional boolean` + - `detail: optional "auto" or "low" or "high"` - 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). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "json_schema"` + - `"auto"` - The type of response format being defined. Always `json_schema`. + - `"low"` - - `"json_schema"` + - `"high"` - - `started_at: number` + - `type: "image_url"` - The Unix timestamp (in seconds) for when the run was started. + The type of the content part. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `"image_url"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `TextContentBlock object { text, type }` - - `"queued"` + The text content that is part of a message. - - `"in_progress"` + - `text: Text` - - `"requires_action"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"cancelling"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"cancelled"` + 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. - - `"failed"` + - `end_index: number` - - `"completed"` + - `file_citation: object { file_id }` - - `"incomplete"` + - `file_id: string` - - `"expired"` + The ID of the specific File the citation is from. - - `thread_id: string` + - `start_index: number` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `text: string` - - `tool_choice: AssistantToolChoiceOption` + The text in the message content that needs to be replaced. - 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: "file_citation"` - - `"none" or "auto" or "required"` + Always `file_citation`. - `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. + - `"file_citation"` - - `"none"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `"auto"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"required"` + - `end_index: number` - - `AssistantToolChoice object { type, function }` + - `file_path: object { file_id }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `file_id: string` - - `type: "function" or "code_interpreter" or "file_search"` + The ID of the file that was generated. - The type of the tool. If type is `function`, the function name must be set + - `start_index: number` - - `"function"` + - `text: string` - - `"code_interpreter"` + The text in the message content that needs to be replaced. - - `"file_search"` + - `type: "file_path"` - - `function: optional AssistantToolChoiceFunction` + Always `file_path`. - - `name: string` + - `"file_path"` - The name of the function to call. + - `value: string` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + The data that makes up the text. - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `type: "text"` - - `CodeInterpreterTool object { type }` + Always `text`. - - `type: "code_interpreter"` + - `"text"` - The type of tool being defined: `code_interpreter` + - `RefusalContentBlock object { refusal, type }` - - `"code_interpreter"` + The refusal content generated by the assistant. - - `FileSearchTool object { type, file_search }` + - `refusal: string` - - `type: "file_search"` + - `type: "refusal"` - The type of tool being defined: `file_search` + Always `refusal`. - - `"file_search"` + - `"refusal"` - - `file_search: optional object { max_num_results, ranking_options }` + - `created_at: number` - Overrides for the file search tool. + The Unix timestamp (in seconds) for when the message was created. - - `max_num_results: optional number` + - `incomplete_at: number` - 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. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - 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. + - `incomplete_details: object { reason }` - - `ranking_options: optional object { score_threshold, ranker }` + On an incomplete message, details about why the message is incomplete. - 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. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The reason the message is incomplete. - - `score_threshold: number` + - `"content_filter"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"max_tokens"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `"run_cancelled"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"run_expired"` - - `"auto"` + - `"run_failed"` - - `"default_2024_08_21"` + - `metadata: Metadata` - - `FunctionTool object { function, type }` + 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. - - `function: FunctionDefinition` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `name: string` + - `object: "thread.message"` - 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. + The object type, which is always `thread.message`. - - `description: optional string` + - `"thread.message"` - A description of what the function does, used by the model to choose when and how to call the function. + - `role: "user" or "assistant"` - - `parameters: optional FunctionParameters` + The entity that produced the message. One of `user` or `assistant`. - 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. + - `"user"` - Omitting `parameters` defines a function with an empty parameter list. + - `"assistant"` - - `strict: optional boolean` + - `run_id: string` - 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). + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `type: "function"` + - `status: "in_progress" or "incomplete" or "completed"` - The type of tool being defined: `function` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"function"` + - `"in_progress"` - - `truncation_strategy: object { type, last_messages }` + - `"incomplete"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"completed"` - - `type: "auto" or "last_messages"` + - `thread_id: string` - 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`. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `"auto"` +### Example - - `"last_messages"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "content": "string", + "role": "user" + }' +``` - - `last_messages: optional number` +#### Response - The number of most recent messages from the thread when constructing the context for the run. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` +### Example - 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.). +```http +curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }' +``` - - `completion_tokens: number` +#### Response - Number of completion tokens used over the course of the run. +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - - `prompt_tokens: number` +## Delete message - Number of prompt tokens used over the course of the run. +**delete** `/threads/{thread_id}/messages/{message_id}` - - `total_tokens: number` +Deletes a message. - Total number of tokens used (prompt + completion). +### Path Parameters - - `temperature: optional number` +- `thread_id: string` - The sampling temperature used for this run. If not set, defaults to 1. +- `message_id: string` - - `top_p: optional number` +### Returns - The nucleus sampling value used for this run. If not set, defaults to 1. +- `MessageDeleted object { id, deleted, object }` -- `first_id: string` + - `id: string` -- `has_more: boolean` + - `deleted: boolean` -- `last_id: string` + - `object: "thread.message.deleted"` -- `object: string` + - `"thread.message.deleted"` ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ + -X DELETE \ -H 'OpenAI-Beta: assistants=v2' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` @@ -2581,82 +2646,18 @@ curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ ```json { - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 - } - ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" + "deleted": true, + "object": "thread.message.deleted" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ +curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" ``` @@ -2664,114 +2665,17 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs \ ```json { - "object": "list", - "data": [ - { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - }, - { - "id": "run_abc456", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - } - ], - "first_id": "run_abc123", - "last_id": "run_abc456", - "has_more": false + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true } ``` -## Create run +## List messages -**post** `/threads/{thread_id}/runs` +**get** `/threads/{thread_id}/messages` -Create a run. +Returns a list of messages for a given thread. ### Path Parameters @@ -2779,39 +2683,77 @@ Create a run. ### Query Parameters -- `include: optional array of RunStepInclude` +- `after: optional string` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. +- `before: optional string` - - `"step_details.tool_calls[*].file_search.results[*].content"` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. -### Body Parameters +- `limit: optional number` -- `assistant_id: string` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. +- `order: optional "asc" or "desc"` -- `additional_instructions: optional string` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - 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. + - `"asc"` -- `additional_messages: optional array of object { content, role, attachments, metadata }` + - `"desc"` - Adds additional messages to the thread before creating the run. +- `run_id: optional string` - - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + Filter messages by the run ID that generated them. - The text contents of the message. +### Returns - - `TextContent = string` +- `data: array of Message` - The text contents of the message. + - `id: string` - - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + The identifier, which can be referenced in API endpoints. - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). + - `assistant_id: string` + + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `CodeInterpreterTool object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `FileSearchTool object { type }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the message was completed. + + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + + The content of the message in array of text and/or images. - `ImageFileContentBlock object { image_file, type }` @@ -2865,501 +2807,496 @@ Create a run. - `"image_url"` - - `TextContentBlockParam object { text, type }` + - `TextContentBlock object { text, type }` The text content that is part of a message. - - `text: string` + - `text: Text` - Text content to be sent to the model + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `type: "text"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - Always `text`. + 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. - - `"text"` + - `end_index: number` - - `role: "user" or "assistant"` + - `file_citation: object { file_id }` - The role of the entity that is creating the message. Allowed values include: + - `file_id: string` - - `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. + The ID of the specific File the citation is from. - - `"user"` + - `start_index: number` - - `"assistant"` + - `text: string` - - `attachments: optional array of object { file_id, tools }` + The text in the message content that needs to be replaced. - A list of files attached to the message, and the tools they should be added to. + - `type: "file_citation"` - - `file_id: optional string` + Always `file_citation`. - The ID of the file to attach to the message. + - `"file_citation"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - The tools to add this file to. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `CodeInterpreterTool object { type }` + - `end_index: number` - - `type: "code_interpreter"` + - `file_path: object { file_id }` - The type of tool being defined: `code_interpreter` + - `file_id: string` - - `"code_interpreter"` + The ID of the file that was generated. - - `FileSearchTool object { type }` + - `start_index: number` - - `type: "file_search"` + - `text: string` - The type of tool being defined: `file_search` + The text in the message content that needs to be replaced. - - `"file_search"` + - `type: "file_path"` - - `metadata: optional Metadata` + Always `file_path`. - 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. + - `"file_path"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `value: string` -- `instructions: optional string` + The data that makes up the text. - Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + - `type: "text"` -- `max_completion_tokens: optional number` + Always `text`. - 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. + - `"text"` -- `max_prompt_tokens: optional number` + - `RefusalContentBlock object { refusal, type }` - 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. + The refusal content generated by the assistant. -- `metadata: optional Metadata` + - `refusal: string` - 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. + - `type: "refusal"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Always `refusal`. -- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `"refusal"` - The ID of the [Model](/docs/api-reference/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. + - `created_at: number` - - `string` + The Unix timestamp (in seconds) for when the message was created. - - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `incomplete_at: number` - The ID of the [Model](/docs/api-reference/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. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"gpt-5"` + - `incomplete_details: object { reason }` - - `"gpt-5-mini"` + On an incomplete message, details about why the message is incomplete. - - `"gpt-5-nano"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `"gpt-5-2025-08-07"` + The reason the message is incomplete. - - `"gpt-5-mini-2025-08-07"` + - `"content_filter"` - - `"gpt-5-nano-2025-08-07"` + - `"max_tokens"` - - `"gpt-4.1"` + - `"run_cancelled"` - - `"gpt-4.1-mini"` + - `"run_expired"` - - `"gpt-4.1-nano"` + - `"run_failed"` - - `"gpt-4.1-2025-04-14"` + - `metadata: Metadata` - - `"gpt-4.1-mini-2025-04-14"` + 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. - - `"gpt-4.1-nano-2025-04-14"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"o3-mini"` + - `object: "thread.message"` - - `"o3-mini-2025-01-31"` + The object type, which is always `thread.message`. - - `"o1"` + - `"thread.message"` - - `"o1-2024-12-17"` + - `role: "user" or "assistant"` - - `"gpt-4o"` + The entity that produced the message. One of `user` or `assistant`. - - `"gpt-4o-2024-11-20"` + - `"user"` - - `"gpt-4o-2024-08-06"` + - `"assistant"` - - `"gpt-4o-2024-05-13"` + - `run_id: string` - - `"gpt-4o-mini"` + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `"gpt-4o-mini-2024-07-18"` + - `status: "in_progress" or "incomplete" or "completed"` - - `"gpt-4.5-preview"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"gpt-4.5-preview-2025-02-27"` + - `"in_progress"` - - `"gpt-4-turbo"` + - `"incomplete"` - - `"gpt-4-turbo-2024-04-09"` + - `"completed"` - - `"gpt-4-0125-preview"` + - `thread_id: string` - - `"gpt-4-turbo-preview"` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `"gpt-4-1106-preview"` +- `first_id: string` - - `"gpt-4-vision-preview"` +- `has_more: boolean` - - `"gpt-4"` +- `last_id: string` - - `"gpt-4-0314"` +- `object: string` - - `"gpt-4-0613"` +### Example - - `"gpt-4-32k"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"gpt-4-32k-0314"` +#### Response - - `"gpt-4-32k-0613"` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` - - `"gpt-3.5-turbo"` +### Example - - `"gpt-3.5-turbo-16k"` +```http +curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"gpt-3.5-turbo-0613"` +#### Response - - `"gpt-3.5-turbo-1106"` +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false +} +``` - - `"gpt-3.5-turbo-0125"` +## Retrieve message - - `"gpt-3.5-turbo-16k-0613"` +**get** `/threads/{thread_id}/messages/{message_id}` -- `parallel_tool_calls: optional boolean` +Retrieve a message. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. +### Path Parameters -- `reasoning_effort: optional ReasoningEffort` +- `thread_id: string` - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://platform.openai.com/docs/guides/reasoning) - for model-specific support. +- `message_id: string` - - `"none"` +### Returns - - `"minimal"` +- `Message object { id, assistant_id, attachments, 11 more }` - - `"low"` + Represents a message within a [thread](/docs/api-reference/threads). - - `"medium"` + - `id: string` - - `"high"` + The identifier, which can be referenced in API endpoints. - - `"xhigh"` + - `assistant_id: string` - - `"max"` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. -- `response_format: optional AssistantResponseFormatOption` + - `attachments: array of object { file_id, tools }` - 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`. + A list of files attached to the message, and the tools they were added to. - 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). + - `file_id: optional string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The ID of the file to attach to the message. - **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. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `"auto"` + The tools to add this file to. - `auto` is the default value + - `CodeInterpreterTool object { type }` - - `"auto"` + - `type: "code_interpreter"` - - `ResponseFormatText object { type }` + The type of tool being defined: `code_interpreter` - Default response format. Used to generate text responses. + - `"code_interpreter"` - - `type: "text"` + - `FileSearchTool object { type }` - The type of response format being defined. Always `text`. + - `type: "file_search"` - - `"text"` + The type of tool being defined: `file_search` - - `ResponseFormatJSONObject object { type }` + - `"file_search"` - 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. + - `completed_at: number` - - `type: "json_object"` + The Unix timestamp (in seconds) for when the message was completed. - The type of response format being defined. Always `json_object`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"json_object"` + The content of the message in array of text and/or images. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `ImageFileContentBlock object { image_file, type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + References an image [File](/docs/api-reference/files) in the content of a message. - - `json_schema: object { name, description, schema, strict }` + - `image_file: ImageFile` - Structured Outputs configuration options, including a JSON Schema. + - `file_id: string` - - `name: string` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - 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. + - `detail: optional "auto" or "low" or "high"` - - `description: optional string` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"auto"` - - `schema: optional map[unknown]` + - `"low"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"high"` - - `strict: optional boolean` + - `type: "image_file"` - 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). + Always `image_file`. - - `type: "json_schema"` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - -- `stream: optional boolean` - - 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. + - `"image_file"` -- `temperature: optional number` + - `ImageURLContentBlock object { image_url, type }` - 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. + References an image URL in the content of a message. -- `tool_choice: optional AssistantToolChoiceOption` + - `image_url: ImageURL` - 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. + - `url: string` - - `"none" or "auto" or "required"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - `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. + - `detail: optional "auto" or "low" or "high"` - - `"none"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `"required"` - - - `AssistantToolChoice object { type, function }` - - Specifies a tool the model should use. Use to force the model to call a specific tool. - - - `type: "function" or "code_interpreter" or "file_search"` - - The type of the tool. If type is `function`, the function name must be set - - - `"function"` - - - `"code_interpreter"` - - - `"file_search"` - - - `function: optional AssistantToolChoiceFunction` - - - `name: string` - - The name of the function to call. - -- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - - - `CodeInterpreterTool object { type }` - - - `FileSearchTool object { type, file_search }` - - - `type: "file_search"` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: optional object { max_num_results, ranking_options }` - - Overrides for the file search tool. - - - `max_num_results: optional number` - - 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: optional object { score_threshold, ranker }` - - 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. + - `"low"` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"high"` - - `score_threshold: number` + - `type: "image_url"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The type of the content part. - - `ranker: optional "auto" or "default_2024_08_21"` + - `"image_url"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `TextContentBlock object { text, type }` - - `"auto"` + The text content that is part of a message. - - `"default_2024_08_21"` + - `text: Text` - - `FunctionTool object { function, type }` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `function: FunctionDefinition` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `name: string` + 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. - 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. + - `end_index: number` - - `description: optional string` + - `file_citation: object { file_id }` - A description of what the function does, used by the model to choose when and how to call the function. + - `file_id: string` - - `parameters: optional FunctionParameters` + The ID of the specific File the citation is from. - 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. + - `start_index: number` - Omitting `parameters` defines a function with an empty parameter list. + - `text: string` - - `strict: optional boolean` + The text in the message content that needs to be replaced. - 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). + - `type: "file_citation"` - - `type: "function"` + Always `file_citation`. - The type of tool being defined: `function` + - `"file_citation"` - - `"function"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` -- `top_p: optional number` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - 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. + - `end_index: number` - We generally recommend altering this or temperature but not both. + - `file_path: object { file_id }` -- `truncation_strategy: optional object { type, last_messages }` + - `file_id: string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The ID of the file that was generated. - - `type: "auto" or "last_messages"` + - `start_index: number` - 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`. + - `text: string` - - `"auto"` + The text in the message content that needs to be replaced. - - `"last_messages"` + - `type: "file_path"` - - `last_messages: optional number` + Always `file_path`. - The number of most recent messages from the thread when constructing the context for the run. + - `"file_path"` -### Returns + - `value: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + The data that makes up the text. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `type: "text"` - - `id: string` + Always `text`. - The identifier, which can be referenced in API endpoints. + - `"text"` - - `assistant_id: string` + - `RefusalContentBlock object { refusal, type }` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + The refusal content generated by the assistant. - - `cancelled_at: number` + - `refusal: string` - The Unix timestamp (in seconds) for when the run was cancelled. + - `type: "refusal"` - - `completed_at: number` + Always `refusal`. - The Unix timestamp (in seconds) for when the run was completed. + - `"refusal"` - `created_at: number` - The Unix timestamp (in seconds) for when the run was created. - - - `expires_at: number` - - The Unix timestamp (in seconds) for when the run will expire. + The Unix timestamp (in seconds) for when the message was created. - - `failed_at: number` + - `incomplete_at: number` - The Unix timestamp (in seconds) for when the run failed. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - `incomplete_details: object { reason }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - - `reason: optional "max_completion_tokens" or "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. - - - `"max_completion_tokens"` - - - `"max_prompt_tokens"` - - - `instructions: string` - - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - - `last_error: object { code, message }` - - The last error associated with this run. Will be `null` if there are no errors. - - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - - `"server_error"` - - - `"rate_limit_exceeded"` + On an incomplete message, details about why the message is incomplete. - - `"invalid_prompt"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `message: string` + The reason the message is incomplete. - A human-readable description of the error. + - `"content_filter"` - - `max_completion_tokens: number` + - `"max_tokens"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"run_cancelled"` - - `max_prompt_tokens: number` + - `"run_expired"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"run_failed"` - `metadata: Metadata` @@ -3370,333 +3307,400 @@ Create a run. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: string` + - `object: "thread.message"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + The object type, which is always `thread.message`. - - `object: "thread.run"` + - `"thread.message"` - The object type, which is always `thread.run`. + - `role: "user" or "assistant"` - - `"thread.run"` + The entity that produced the message. One of `user` or `assistant`. - - `parallel_tool_calls: boolean` + - `"user"` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"assistant"` - - `required_action: object { submit_tool_outputs, type }` + - `run_id: string` - Details on the action required to continue the run. Will be `null` if no action is required. + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `submit_tool_outputs: object { tool_calls }` + - `status: "in_progress" or "incomplete" or "completed"` - Details on the tool outputs needed for this run to continue. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `"in_progress"` - A list of the relevant tool calls. + - `"incomplete"` - - `id: string` + - `"completed"` - 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. + - `thread_id: string` - - `function: object { arguments, name }` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The function definition. +### Example - - `arguments: string` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The arguments that the model expects you to pass to the function. +#### Response - - `name: string` - - The name of the function. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `type: "function"` +### Example - The type of tool call the output is required for. For now, this is always `function`. +```http +curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"function"` +#### Response - - `type: "submit_tool_outputs"` +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - For now, this is always `submit_tool_outputs`. +## Modify message - - `"submit_tool_outputs"` +**post** `/threads/{thread_id}/messages/{message_id}` - - `response_format: AssistantResponseFormatOption` +Modifies a message. - 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`. +### Path Parameters - 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). +- `thread_id: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. +- `message_id: string` - **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. +### Body Parameters - - `"auto"` +- `metadata: optional Metadata` - `auto` is the default value + 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. - - `"auto"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ResponseFormatText object { type }` +### Returns - Default response format. Used to generate text responses. +- `Message object { id, assistant_id, attachments, 11 more }` - - `type: "text"` + Represents a message within a [thread](/docs/api-reference/threads). - The type of response format being defined. Always `text`. + - `id: string` - - `"text"` + The identifier, which can be referenced in API endpoints. - - `ResponseFormatJSONObject object { type }` + - `assistant_id: string` - 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. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `type: "json_object"` + - `attachments: array of object { file_id, tools }` - The type of response format being defined. Always `json_object`. + A list of files attached to the message, and the tools they were added to. - - `"json_object"` + - `file_id: optional string` - - `ResponseFormatJSONSchema object { json_schema, type }` + The ID of the file to attach to the message. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `tools: optional array of CodeInterpreterTool or object { type }` - - `json_schema: object { name, description, schema, strict }` + The tools to add this file to. - Structured Outputs configuration options, including a JSON Schema. + - `CodeInterpreterTool object { type }` - - `name: string` + - `type: "code_interpreter"` - 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. + The type of tool being defined: `code_interpreter` - - `description: optional string` + - `"code_interpreter"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `FileSearchTool object { type }` - - `schema: optional map[unknown]` + - `type: "file_search"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of tool being defined: `file_search` - - `strict: optional boolean` + - `"file_search"` - 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). + - `completed_at: number` - - `type: "json_schema"` + The Unix timestamp (in seconds) for when the message was completed. - The type of response format being defined. Always `json_schema`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"json_schema"` + The content of the message in array of text and/or images. - - `started_at: number` + - `ImageFileContentBlock object { image_file, type }` - The Unix timestamp (in seconds) for when the run was started. + References an image [File](/docs/api-reference/files) in the content of a message. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `image_file: ImageFile` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `file_id: string` - - `"queued"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"in_progress"` + - `detail: optional "auto" or "low" or "high"` - - `"requires_action"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"cancelling"` + - `"auto"` - - `"cancelled"` + - `"low"` - - `"failed"` + - `"high"` - - `"completed"` + - `type: "image_file"` - - `"incomplete"` + Always `image_file`. - - `"expired"` + - `"image_file"` - - `thread_id: string` + - `ImageURLContentBlock object { image_url, type }` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + References an image URL in the content of a message. - - `tool_choice: AssistantToolChoiceOption` + - `image_url: ImageURL` - 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. + - `url: string` - - `"none" or "auto" or "required"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - `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. + - `detail: optional "auto" or "low" or "high"` - - `"none"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `"required"` + - `"low"` - - `AssistantToolChoice object { type, function }` + - `"high"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `type: "image_url"` - - `type: "function" or "code_interpreter" or "file_search"` + The type of the content part. - The type of the tool. If type is `function`, the function name must be set + - `"image_url"` - - `"function"` + - `TextContentBlock object { text, type }` - - `"code_interpreter"` + The text content that is part of a message. - - `"file_search"` + - `text: Text` - - `function: optional AssistantToolChoiceFunction` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `name: string` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - The name of the function to call. + 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. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `end_index: number` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `file_citation: object { file_id }` - - `CodeInterpreterTool object { type }` + - `file_id: string` - - `type: "code_interpreter"` + The ID of the specific File the citation is from. - The type of tool being defined: `code_interpreter` + - `start_index: number` - - `"code_interpreter"` + - `text: string` - - `FileSearchTool object { type, file_search }` + The text in the message content that needs to be replaced. - - `type: "file_search"` + - `type: "file_citation"` - The type of tool being defined: `file_search` + Always `file_citation`. - - `"file_search"` + - `"file_citation"` - - `file_search: optional object { max_num_results, ranking_options }` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - Overrides for the file search tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `max_num_results: optional number` + - `end_index: number` - 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. + - `file_path: object { file_id }` - 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. + - `file_id: string` - - `ranking_options: optional object { score_threshold, ranker }` + The ID of the file that was generated. - 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. + - `start_index: number` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `text: string` - - `score_threshold: number` + The text in the message content that needs to be replaced. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `type: "file_path"` - - `ranker: optional "auto" or "default_2024_08_21"` + Always `file_path`. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"file_path"` - - `"auto"` + - `value: string` - - `"default_2024_08_21"` + The data that makes up the text. - - `FunctionTool object { function, type }` + - `type: "text"` - - `function: FunctionDefinition` + Always `text`. - - `name: string` + - `"text"` - 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. + - `RefusalContentBlock object { refusal, type }` - - `description: optional string` + The refusal content generated by the assistant. - A description of what the function does, used by the model to choose when and how to call the function. + - `refusal: string` - - `parameters: optional FunctionParameters` + - `type: "refusal"` - 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. + Always `refusal`. - Omitting `parameters` defines a function with an empty parameter list. + - `"refusal"` - - `strict: optional boolean` + - `created_at: number` - 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). + The Unix timestamp (in seconds) for when the message was created. - - `type: "function"` + - `incomplete_at: number` - The type of tool being defined: `function` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"function"` + - `incomplete_details: object { reason }` - - `truncation_strategy: object { type, last_messages }` + On an incomplete message, details about why the message is incomplete. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `type: "auto" or "last_messages"` + The reason the message is incomplete. - 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`. + - `"content_filter"` - - `"auto"` + - `"max_tokens"` - - `"last_messages"` + - `"run_cancelled"` - - `last_messages: optional number` + - `"run_expired"` - The number of most recent messages from the thread when constructing the context for the run. + - `"run_failed"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `metadata: Metadata` - 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.). + 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. - - `completion_tokens: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Number of completion tokens used over the course of the run. + - `object: "thread.message"` - - `prompt_tokens: number` + The object type, which is always `thread.message`. - Number of prompt tokens used over the course of the run. + - `"thread.message"` - - `total_tokens: number` + - `role: "user" or "assistant"` - Total number of tokens used (prompt + completion). + The entity that produced the message. One of `user` or `assistant`. - - `temperature: optional number` + - `"user"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"assistant"` - - `top_p: optional number` + - `run_id: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](/docs/api-reference/threads) ID that this message belongs to. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "assistant_id": "assistant_id", - "temperature": 1, - "top_p": 1 - }' + -d '{}' ``` #### Response @@ -3705,75 +3709,54 @@ curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ { "id": "id", "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ + "attachments": [ { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", + "file_id": "file_id", "tools": [ { "type": "code_interpreter" } + ] + } ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" }, - "temperature": 0, - "top_p": 0 + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ +curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ - "assistant_id": "asst_abc123" + "metadata": { + "modified": "true", + "user": "abc123" + } }' ``` @@ -3781,486 +3764,365 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs \ ```json { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, "thread_id": "thread_abc123", - "status": "queued", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ + "run_id": null, + "role": "user", + "content": [ { - "type": "code_interpreter" + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } } ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } } ``` -### Streaming +## Domain Types -```http -curl https://api.openai.com/v1/threads/thread_123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_123", - "stream": true - }' -``` +### File Citation Annotation -#### Response +- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + 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. -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `end_index: number` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `file_citation: object { file_id }` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `file_id: string` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + The ID of the specific File the citation is from. -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `start_index: number` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `text: string` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + The text in the message content that needs to be replaced. -... + - `type: "file_citation"` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + Always `file_citation`. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + - `"file_citation"` -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} +### File Citation Delta Annotation -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} +- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + 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. -event: done -data: [DONE] -``` + - `index: number` -### Streaming with Functions + The index of the annotation in the text content part. -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_abc123", - "tools": [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } - }, - "required": ["location"] - } - } - } - ], - "stream": true - }' -``` + - `type: "file_citation"` -#### Response + Always `file_citation`. -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `"file_citation"` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `end_index: optional number` -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `file_citation: optional object { file_id, quote }` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `file_id: optional string` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + The ID of the specific File the citation is from. -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `quote: optional string` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + The specific quote in the file. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `start_index: optional number` -... + - `text: optional string` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + The text in the message content that needs to be replaced. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} +### File Path Annotation -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} +- `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `end_index: number` -event: done -data: [DONE] -``` + - `file_path: object { file_id }` -## Retrieve run + - `file_id: string` -**get** `/threads/{thread_id}/runs/{run_id}` + The ID of the file that was generated. -Retrieves a run. + - `start_index: number` -### Path Parameters + - `text: string` -- `thread_id: string` + The text in the message content that needs to be replaced. -- `run_id: string` + - `type: "file_path"` -### Returns + Always `file_path`. -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `"file_path"` - Represents an execution run on a [thread](/docs/api-reference/threads). +### File Path Delta Annotation - - `id: string` +- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - The identifier, which can be referenced in API endpoints. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `assistant_id: string` + - `index: number` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + The index of the annotation in the text content part. - - `cancelled_at: number` + - `type: "file_path"` - The Unix timestamp (in seconds) for when the run was cancelled. + Always `file_path`. - - `completed_at: number` + - `"file_path"` - The Unix timestamp (in seconds) for when the run was completed. + - `end_index: optional number` - - `created_at: number` + - `file_path: optional object { file_id }` - The Unix timestamp (in seconds) for when the run was created. + - `file_id: optional string` - - `expires_at: number` + The ID of the file that was generated. - The Unix timestamp (in seconds) for when the run will expire. + - `start_index: optional number` - - `failed_at: number` + - `text: optional string` - The Unix timestamp (in seconds) for when the run failed. + The text in the message content that needs to be replaced. - - `incomplete_details: object { reason }` +### Image File - Details on why the run is incomplete. Will be `null` if the run is not incomplete. +- `ImageFile object { file_id, detail }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `file_id: string` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"max_completion_tokens"` + - `detail: optional "auto" or "low" or "high"` - - `"max_prompt_tokens"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `instructions: string` + - `"auto"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `"low"` - - `last_error: object { code, message }` + - `"high"` - The last error associated with this run. Will be `null` if there are no errors. +### Image File Content Block - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` +- `ImageFileContentBlock object { image_file, type }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + References an image [File](/docs/api-reference/files) in the content of a message. - - `"server_error"` + - `image_file: ImageFile` - - `"rate_limit_exceeded"` + - `file_id: string` - - `"invalid_prompt"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `message: string` + - `detail: optional "auto" or "low" or "high"` - A human-readable description of the error. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `max_completion_tokens: number` + - `"auto"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"low"` - - `max_prompt_tokens: number` + - `"high"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `type: "image_file"` - - `metadata: Metadata` + Always `image_file`. - 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. + - `"image_file"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +### Image File Delta - - `model: string` +- `ImageFileDelta object { detail, file_id }` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `detail: optional "auto" or "low" or "high"` - - `object: "thread.run"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The object type, which is always `thread.run`. + - `"auto"` - - `"thread.run"` + - `"low"` - - `parallel_tool_calls: boolean` + - `"high"` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `file_id: optional string` - - `required_action: object { submit_tool_outputs, type }` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Details on the action required to continue the run. Will be `null` if no action is required. +### Image File Delta Block - - `submit_tool_outputs: object { tool_calls }` +- `ImageFileDeltaBlock object { index, type, image_file }` - Details on the tool outputs needed for this run to continue. + References an image [File](/docs/api-reference/files) in the content of a message. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `index: number` - A list of the relevant tool calls. + The index of the content part in the message. - - `id: string` + - `type: "image_file"` - 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. + Always `image_file`. - - `function: object { arguments, name }` - - The function definition. - - - `arguments: string` - - The arguments that the model expects you to pass to the function. - - - `name: string` + - `"image_file"` - The name of the function. + - `image_file: optional ImageFileDelta` - - `type: "function"` + - `detail: optional "auto" or "low" or "high"` - The type of tool call the output is required for. For now, this is always `function`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"function"` + - `"auto"` - - `type: "submit_tool_outputs"` + - `"low"` - For now, this is always `submit_tool_outputs`. + - `"high"` - - `"submit_tool_outputs"` + - `file_id: optional string` - - `response_format: AssistantResponseFormatOption` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - 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`. +### Image URL - 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). +- `ImageURL object { url, detail }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `url: string` - **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. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"auto"` + - `detail: optional "auto" or "low" or "high"` - `auto` is the default value + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `ResponseFormatText object { type }` - - Default response format. Used to generate text responses. - - - `type: "text"` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `ResponseFormatJSONObject object { type }` + - `"low"` - 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. + - `"high"` - - `type: "json_object"` +### Image URL Content Block - The type of response format being defined. Always `json_object`. +- `ImageURLContentBlock object { image_url, type }` - - `"json_object"` + References an image URL in the content of a message. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `image_url: ImageURL` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `url: string` - - `json_schema: object { name, description, schema, strict }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Structured Outputs configuration options, including a JSON Schema. + - `detail: optional "auto" or "low" or "high"` - - `name: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - 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. + - `"auto"` - - `description: optional string` + - `"low"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"high"` - - `schema: optional map[unknown]` + - `type: "image_url"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the content part. - - `strict: optional boolean` + - `"image_url"` - 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). +### Image URL Delta - - `type: "json_schema"` +- `ImageURLDelta object { detail, url }` - The type of response format being defined. Always `json_schema`. + - `detail: optional "auto" or "low" or "high"` - - `"json_schema"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `started_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run was started. + - `"low"` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `"high"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `url: optional string` - - `"queued"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"in_progress"` +### Image URL Delta Block - - `"requires_action"` +- `ImageURLDeltaBlock object { index, type, image_url }` - - `"cancelling"` + References an image URL in the content of a message. - - `"cancelled"` + - `index: number` - - `"failed"` + The index of the content part in the message. - - `"completed"` + - `type: "image_url"` - - `"incomplete"` + Always `image_url`. - - `"expired"` + - `"image_url"` - - `thread_id: string` + - `image_url: optional ImageURLDelta` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `detail: optional "auto" or "low" or "high"` - - `tool_choice: AssistantToolChoiceOption` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - 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. + - `"auto"` - - `"none" or "auto" or "required"` + - `"low"` - `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. + - `"high"` - - `"none"` + - `url: optional string` - - `"auto"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"required"` +### Message - - `AssistantToolChoice object { type, function }` +- `Message object { id, assistant_id, attachments, 11 more }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Represents a message within a [thread](/docs/api-reference/threads). - - `type: "function" or "code_interpreter" or "file_search"` + - `id: string` - The type of the tool. If type is `function`, the function name must be set + The identifier, which can be referenced in API endpoints. - - `"function"` + - `assistant_id: string` - - `"code_interpreter"` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"file_search"` + - `attachments: array of object { file_id, tools }` - - `function: optional AssistantToolChoiceFunction` + A list of files attached to the message, and the tools they were added to. - - `name: string` + - `file_id: optional string` - The name of the function to call. + The ID of the file to attach to the message. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `tools: optional array of CodeInterpreterTool or object { type }` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + The tools to add this file to. - `CodeInterpreterTool object { type }` @@ -4270,7 +4132,7 @@ Retrieves a run. - `"code_interpreter"` - - `FileSearchTool object { type, file_search }` + - `FileSearchTool object { type }` - `type: "file_search"` @@ -4278,1494 +4140,962 @@ Retrieves a run. - `"file_search"` - - `file_search: optional object { max_num_results, ranking_options }` - - Overrides for the file search tool. + - `completed_at: number` - - `max_num_results: optional number` + The Unix timestamp (in seconds) for when the message was completed. - 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. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - 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. + The content of the message in array of text and/or images. - - `ranking_options: optional object { score_threshold, ranker }` + - `ImageFileContentBlock object { image_file, type }` - 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. + References an image [File](/docs/api-reference/files) in the content of a message. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `image_file: ImageFile` - - `score_threshold: number` + - `file_id: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `ranker: optional "auto" or "default_2024_08_21"` + - `detail: optional "auto" or "low" or "high"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` - - `"default_2024_08_21"` + - `"low"` - - `FunctionTool object { function, type }` + - `"high"` - - `function: FunctionDefinition` + - `type: "image_file"` - - `name: string` + Always `image_file`. - 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. + - `"image_file"` - - `description: optional string` + - `ImageURLContentBlock object { image_url, type }` - A description of what the function does, used by the model to choose when and how to call the function. + References an image URL in the content of a message. - - `parameters: optional FunctionParameters` + - `image_url: ImageURL` - 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. + - `url: string` - Omitting `parameters` defines a function with an empty parameter list. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `strict: optional boolean` + - `detail: optional "auto" or "low" or "high"` - 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). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "function"` + - `"auto"` - The type of tool being defined: `function` + - `"low"` - - `"function"` + - `"high"` - - `truncation_strategy: object { type, last_messages }` + - `type: "image_url"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The type of the content part. - - `type: "auto" or "last_messages"` + - `"image_url"` - 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`. + - `TextContentBlock object { text, type }` - - `"auto"` + The text content that is part of a message. - - `"last_messages"` + - `text: Text` - - `last_messages: optional number` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The number of most recent messages from the thread when constructing the context for the run. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + 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. - 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.). + - `end_index: number` - - `completion_tokens: number` + - `file_citation: object { file_id }` - Number of completion tokens used over the course of the run. + - `file_id: string` - - `prompt_tokens: number` + The ID of the specific File the citation is from. - Number of prompt tokens used over the course of the run. + - `start_index: number` - - `total_tokens: number` + - `text: string` - Total number of tokens used (prompt + completion). + The text in the message content that needs to be replaced. - - `temperature: optional number` + - `type: "file_citation"` - The sampling temperature used for this run. If not set, defaults to 1. + Always `file_citation`. - - `top_p: optional number` + - `"file_citation"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` -### Example + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `end_index: number` -#### Response + - `file_path: object { file_id }` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `file_id: string` -### Example + The ID of the file that was generated. -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `start_index: number` -#### Response + - `text: string` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The text in the message content that needs to be replaced. -## Modify run + - `type: "file_path"` -**post** `/threads/{thread_id}/runs/{run_id}` + Always `file_path`. -Modifies a run. + - `"file_path"` -### Path Parameters + - `value: string` -- `thread_id: string` + The data that makes up the text. -- `run_id: string` + - `type: "text"` -### Body Parameters + Always `text`. -- `metadata: optional Metadata` + - `"text"` - 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. + - `RefusalContentBlock object { refusal, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The refusal content generated by the assistant. -### Returns + - `refusal: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `type: "refusal"` - Represents an execution run on a [thread](/docs/api-reference/threads). + Always `refusal`. - - `id: string` + - `"refusal"` - The identifier, which can be referenced in API endpoints. + - `created_at: number` - - `assistant_id: string` + The Unix timestamp (in seconds) for when the message was created. - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `incomplete_at: number` - - `cancelled_at: number` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - The Unix timestamp (in seconds) for when the run was cancelled. + - `incomplete_details: object { reason }` - - `completed_at: number` + On an incomplete message, details about why the message is incomplete. - The Unix timestamp (in seconds) for when the run was completed. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `created_at: number` + The reason the message is incomplete. - The Unix timestamp (in seconds) for when the run was created. + - `"content_filter"` - - `expires_at: number` + - `"max_tokens"` - The Unix timestamp (in seconds) for when the run will expire. + - `"run_cancelled"` - - `failed_at: number` + - `"run_expired"` - The Unix timestamp (in seconds) for when the run failed. + - `"run_failed"` - - `incomplete_details: object { reason }` + - `metadata: Metadata` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + 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. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `object: "thread.message"` - - `"max_completion_tokens"` + The object type, which is always `thread.message`. - - `"max_prompt_tokens"` + - `"thread.message"` - - `instructions: string` + - `role: "user" or "assistant"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + The entity that produced the message. One of `user` or `assistant`. - - `last_error: object { code, message }` + - `"user"` - The last error associated with this run. Will be `null` if there are no errors. + - `"assistant"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `run_id: string` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `"server_error"` + - `status: "in_progress" or "incomplete" or "completed"` - - `"rate_limit_exceeded"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"invalid_prompt"` + - `"in_progress"` - - `message: string` + - `"incomplete"` - A human-readable description of the error. + - `"completed"` - - `max_completion_tokens: number` + - `thread_id: string` - The maximum number of completion tokens specified to have been used over the course of the run. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `max_prompt_tokens: number` +### Message Deleted - The maximum number of prompt tokens specified to have been used over the course of the run. +- `MessageDeleted object { id, deleted, object }` - - `metadata: Metadata` + - `id: string` - 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. + - `deleted: boolean` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `object: "thread.message.deleted"` - - `model: string` + - `"thread.message.deleted"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. +### Message Delta - - `object: "thread.run"` +- `MessageDelta object { content, role }` - The object type, which is always `thread.run`. + The delta containing the fields that have changed on the Message. - - `"thread.run"` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `parallel_tool_calls: boolean` + The content of the message in array of text and/or images. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `ImageFileDeltaBlock object { index, type, image_file }` - - `required_action: object { submit_tool_outputs, type }` + References an image [File](/docs/api-reference/files) in the content of a message. - Details on the action required to continue the run. Will be `null` if no action is required. + - `index: number` - - `submit_tool_outputs: object { tool_calls }` + The index of the content part in the message. - Details on the tool outputs needed for this run to continue. + - `type: "image_file"` - - `tool_calls: array of RequiredActionFunctionToolCall` + Always `image_file`. - A list of the relevant tool calls. + - `"image_file"` - - `id: string` + - `image_file: optional ImageFileDelta` - 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. + - `detail: optional "auto" or "low" or "high"` - - `function: object { arguments, name }` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The function definition. + - `"auto"` - - `arguments: string` + - `"low"` - The arguments that the model expects you to pass to the function. + - `"high"` - - `name: string` + - `file_id: optional string` - The name of the function. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `type: "function"` + - `TextDeltaBlock object { index, type, text }` - The type of tool call the output is required for. For now, this is always `function`. + The text content that is part of a message. - - `"function"` + - `index: number` - - `type: "submit_tool_outputs"` + The index of the content part in the message. - For now, this is always `submit_tool_outputs`. + - `type: "text"` - - `"submit_tool_outputs"` + Always `text`. - - `response_format: AssistantResponseFormatOption` + - `"text"` - 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`. + - `text: optional TextDelta` - 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). + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - **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. + 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. - - `"auto"` + - `index: number` - `auto` is the default value + The index of the annotation in the text content part. - - `"auto"` + - `type: "file_citation"` - - `ResponseFormatText object { type }` + Always `file_citation`. - Default response format. Used to generate text responses. + - `"file_citation"` - - `type: "text"` + - `end_index: optional number` - The type of response format being defined. Always `text`. + - `file_citation: optional object { file_id, quote }` - - `"text"` + - `file_id: optional string` - - `ResponseFormatJSONObject object { type }` + The ID of the specific File the citation is from. - 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. + - `quote: optional string` - - `type: "json_object"` + The specific quote in the file. - The type of response format being defined. Always `json_object`. + - `start_index: optional number` - - `"json_object"` + - `text: optional string` - - `ResponseFormatJSONSchema object { json_schema, type }` + The text in the message content that needs to be replaced. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `json_schema: object { name, description, schema, strict }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - Structured Outputs configuration options, including a JSON Schema. + - `index: number` - - `name: string` + The index of the annotation in the text content part. - 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. + - `type: "file_path"` - - `description: optional string` + Always `file_path`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"file_path"` - - `schema: optional map[unknown]` + - `end_index: optional number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `file_path: optional object { file_id }` - - `strict: optional boolean` + - `file_id: optional string` - 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). + The ID of the file that was generated. - - `type: "json_schema"` + - `start_index: optional number` - The type of response format being defined. Always `json_schema`. + - `text: optional string` - - `"json_schema"` + The text in the message content that needs to be replaced. - - `started_at: number` + - `value: optional string` - The Unix timestamp (in seconds) for when the run was started. + The data that makes up the text. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `RefusalDeltaBlock object { index, type, refusal }` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + The refusal content that is part of a message. - - `"queued"` + - `index: number` - - `"in_progress"` + The index of the refusal part in the message. - - `"requires_action"` + - `type: "refusal"` - - `"cancelling"` + Always `refusal`. - - `"cancelled"` + - `"refusal"` - - `"failed"` + - `refusal: optional string` - - `"completed"` + - `ImageURLDeltaBlock object { index, type, image_url }` - - `"incomplete"` + References an image URL in the content of a message. - - `"expired"` + - `index: number` - - `thread_id: string` + The index of the content part in the message. - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `type: "image_url"` - - `tool_choice: AssistantToolChoiceOption` + Always `image_url`. - 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. + - `"image_url"` - - `"none" or "auto" or "required"` + - `image_url: optional ImageURLDelta` - `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. + - `detail: optional "auto" or "low" or "high"` - - `"none"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` - - `"required"` + - `"low"` - - `AssistantToolChoice object { type, function }` + - `"high"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `url: optional string` - - `type: "function" or "code_interpreter" or "file_search"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the tool. If type is `function`, the function name must be set + - `role: optional "user" or "assistant"` - - `"function"` + The entity that produced the message. One of `user` or `assistant`. - - `"code_interpreter"` + - `"user"` - - `"file_search"` + - `"assistant"` - - `function: optional AssistantToolChoiceFunction` +### Message Delta Event - - `name: string` +- `MessageDeltaEvent object { id, delta, object }` - The name of the function to call. + Represents a message delta i.e. any changed fields on a message during streaming. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `id: string` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + The identifier of the message, which can be referenced in API endpoints. - - `CodeInterpreterTool object { type }` + - `delta: MessageDelta` - - `type: "code_interpreter"` + The delta containing the fields that have changed on the Message. - The type of tool being defined: `code_interpreter` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `"code_interpreter"` + The content of the message in array of text and/or images. - - `FileSearchTool object { type, file_search }` + - `ImageFileDeltaBlock object { index, type, image_file }` - - `type: "file_search"` + References an image [File](/docs/api-reference/files) in the content of a message. - The type of tool being defined: `file_search` + - `index: number` - - `"file_search"` + The index of the content part in the message. - - `file_search: optional object { max_num_results, ranking_options }` + - `type: "image_file"` - Overrides for the file search tool. + Always `image_file`. - - `max_num_results: optional number` + - `"image_file"` - 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. + - `image_file: optional ImageFileDelta` - 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. + - `detail: optional "auto" or "low" or "high"` - - `ranking_options: optional object { score_threshold, ranker }` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - 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. + - `"auto"` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"low"` - - `score_threshold: number` + - `"high"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `file_id: optional string` - - `ranker: optional "auto" or "default_2024_08_21"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `TextDeltaBlock object { index, type, text }` - - `"auto"` + The text content that is part of a message. - - `"default_2024_08_21"` + - `index: number` - - `FunctionTool object { function, type }` + The index of the content part in the message. - - `function: FunctionDefinition` + - `type: "text"` - - `name: string` + Always `text`. - 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. + - `"text"` - - `description: optional string` + - `text: optional TextDelta` - A description of what the function does, used by the model to choose when and how to call the function. + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `parameters: optional FunctionParameters` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - 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. + 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. - Omitting `parameters` defines a function with an empty parameter list. + - `index: number` - - `strict: optional boolean` + The index of the annotation in the text content part. - 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). + - `type: "file_citation"` - - `type: "function"` + Always `file_citation`. - The type of tool being defined: `function` + - `"file_citation"` - - `"function"` + - `end_index: optional number` - - `truncation_strategy: object { type, last_messages }` + - `file_citation: optional object { file_id, quote }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `file_id: optional string` - - `type: "auto" or "last_messages"` + The ID of the specific File the citation is from. - 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`. + - `quote: optional string` - - `"auto"` + The specific quote in the file. - - `"last_messages"` + - `start_index: optional number` - - `last_messages: optional number` + - `text: optional string` - The number of most recent messages from the thread when constructing the context for the run. + The text in the message content that needs to be replaced. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - 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.). + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `completion_tokens: number` + - `index: number` - Number of completion tokens used over the course of the run. + The index of the annotation in the text content part. - - `prompt_tokens: number` + - `type: "file_path"` - Number of prompt tokens used over the course of the run. + Always `file_path`. - - `total_tokens: number` + - `"file_path"` - Total number of tokens used (prompt + completion). + - `end_index: optional number` - - `temperature: optional number` + - `file_path: optional object { file_id }` - The sampling temperature used for this run. If not set, defaults to 1. + - `file_id: optional string` - - `top_p: optional number` + The ID of the file that was generated. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `start_index: optional number` -### Example + - `text: optional string` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{}' -``` + The text in the message content that needs to be replaced. -#### Response + - `value: optional string` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The data that makes up the text. -### Example + - `RefusalDeltaBlock object { index, type, refusal }` -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "user_id": "user_abc123" - } - }' -``` + The refusal content that is part of a message. -#### Response + - `index: number` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": { - "user_id": "user_abc123" - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The index of the refusal part in the message. -## Submit tool outputs to run + - `type: "refusal"` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + Always `refusal`. -When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. + - `"refusal"` -### Path Parameters + - `refusal: optional string` -- `thread_id: string` + - `ImageURLDeltaBlock object { index, type, image_url }` -- `run_id: string` + References an image URL in the content of a message. -### Body Parameters + - `index: number` -- `tool_outputs: array of object { output, tool_call_id }` + The index of the content part in the message. - A list of tools for which the outputs are being submitted. + - `type: "image_url"` - - `output: optional string` + Always `image_url`. - The output of the tool call to be submitted to continue the run. + - `"image_url"` - - `tool_call_id: optional string` + - `image_url: optional ImageURLDelta` - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + - `detail: optional "auto" or "low" or "high"` -- `stream: optional boolean` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - 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. + - `"auto"` -### Returns + - `"low"` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `"high"` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `url: optional string` - - `id: string` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The identifier, which can be referenced in API endpoints. + - `role: optional "user" or "assistant"` - - `assistant_id: string` + The entity that produced the message. One of `user` or `assistant`. - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `"user"` - - `cancelled_at: number` + - `"assistant"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `object: "thread.message.delta"` - - `completed_at: number` + The object type, which is always `thread.message.delta`. - The Unix timestamp (in seconds) for when the run was completed. + - `"thread.message.delta"` - - `created_at: number` +### Refusal Content Block - The Unix timestamp (in seconds) for when the run was created. +- `RefusalContentBlock object { refusal, type }` - - `expires_at: number` + The refusal content generated by the assistant. - The Unix timestamp (in seconds) for when the run will expire. + - `refusal: string` - - `failed_at: number` + - `type: "refusal"` - The Unix timestamp (in seconds) for when the run failed. + Always `refusal`. - - `incomplete_details: object { reason }` + - `"refusal"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. +### Refusal Delta Block - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` +- `RefusalDeltaBlock object { index, type, refusal }` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The refusal content that is part of a message. - - `"max_completion_tokens"` + - `index: number` - - `"max_prompt_tokens"` + The index of the refusal part in the message. - - `instructions: string` + - `type: "refusal"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + Always `refusal`. - - `last_error: object { code, message }` + - `"refusal"` - The last error associated with this run. Will be `null` if there are no errors. + - `refusal: optional string` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` +### Text - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. +- `Text object { annotations, value }` - - `"server_error"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"rate_limit_exceeded"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"invalid_prompt"` + 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. - - `message: string` + - `end_index: number` - A human-readable description of the error. + - `file_citation: object { file_id }` - - `max_completion_tokens: number` + - `file_id: string` - The maximum number of completion tokens specified to have been used over the course of the run. + The ID of the specific File the citation is from. - - `max_prompt_tokens: number` + - `start_index: number` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `text: string` - - `metadata: Metadata` + The text in the message content that needs to be replaced. - 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. + - `type: "file_citation"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Always `file_citation`. - - `model: string` + - `"file_citation"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `object: "thread.run"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The object type, which is always `thread.run`. + - `end_index: number` - - `"thread.run"` + - `file_path: object { file_id }` - - `parallel_tool_calls: boolean` + - `file_id: string` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + The ID of the file that was generated. - - `required_action: object { submit_tool_outputs, type }` + - `start_index: number` - Details on the action required to continue the run. Will be `null` if no action is required. + - `text: string` - - `submit_tool_outputs: object { tool_calls }` + The text in the message content that needs to be replaced. - Details on the tool outputs needed for this run to continue. + - `type: "file_path"` - - `tool_calls: array of RequiredActionFunctionToolCall` + Always `file_path`. - A list of the relevant tool calls. + - `"file_path"` - - `id: string` + - `value: string` - 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. + The data that makes up the text. - - `function: object { arguments, name }` +### Text Content Block - The function definition. +- `TextContentBlock object { text, type }` - - `arguments: string` + The text content that is part of a message. - The arguments that the model expects you to pass to the function. + - `text: Text` - - `name: string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The name of the function. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `type: "function"` + 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. - The type of tool call the output is required for. For now, this is always `function`. + - `end_index: number` - - `"function"` + - `file_citation: object { file_id }` - - `type: "submit_tool_outputs"` + - `file_id: string` - For now, this is always `submit_tool_outputs`. + The ID of the specific File the citation is from. - - `"submit_tool_outputs"` + - `start_index: number` - - `response_format: AssistantResponseFormatOption` + - `text: string` - 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`. + The text in the message content that needs to be replaced. - 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). + - `type: "file_citation"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Always `file_citation`. - **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. + - `"file_citation"` - - `"auto"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - `auto` is the default value + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"auto"` + - `end_index: number` - - `ResponseFormatText object { type }` + - `file_path: object { file_id }` - Default response format. Used to generate text responses. + - `file_id: string` - - `type: "text"` + The ID of the file that was generated. - The type of response format being defined. Always `text`. + - `start_index: number` - - `"text"` + - `text: string` - - `ResponseFormatJSONObject object { type }` + The text in the message content that needs to be replaced. - 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: "file_path"` - - `type: "json_object"` + Always `file_path`. - The type of response format being defined. Always `json_object`. + - `"file_path"` - - `"json_object"` + - `value: string` - - `ResponseFormatJSONSchema object { json_schema, type }` + The data that makes up the text. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `type: "text"` - - `json_schema: object { name, description, schema, strict }` + Always `text`. - Structured Outputs configuration options, including a JSON Schema. + - `"text"` - - `name: string` +### Text Content Block Param - 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. +- `TextContentBlockParam object { text, type }` - - `description: optional string` + The text content that is part of a message. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `text: string` - - `schema: optional map[unknown]` + Text content to be sent to the model - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `type: "text"` - - `strict: optional boolean` + Always `text`. - 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). + - `"text"` - - `type: "json_schema"` +### Text Delta - The type of response format being defined. Always `json_schema`. +- `TextDelta object { annotations, value }` - - `"json_schema"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `started_at: number` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - The Unix timestamp (in seconds) for when the run was started. + 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. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `index: number` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + The index of the annotation in the text content part. - - `"queued"` + - `type: "file_citation"` - - `"in_progress"` + Always `file_citation`. - - `"requires_action"` + - `"file_citation"` - - `"cancelling"` + - `end_index: optional number` - - `"cancelled"` + - `file_citation: optional object { file_id, quote }` - - `"failed"` + - `file_id: optional string` - - `"completed"` + The ID of the specific File the citation is from. - - `"incomplete"` + - `quote: optional string` - - `"expired"` + The specific quote in the file. - - `thread_id: string` + - `start_index: optional number` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `text: optional string` - - `tool_choice: AssistantToolChoiceOption` + The text in the message content that needs to be replaced. - 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. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `"none" or "auto" or "required"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - `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. + - `index: number` - - `"none"` + The index of the annotation in the text content part. - - `"auto"` + - `type: "file_path"` - - `"required"` + Always `file_path`. - - `AssistantToolChoice object { type, function }` + - `"file_path"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `end_index: optional number` - - `type: "function" or "code_interpreter" or "file_search"` + - `file_path: optional object { file_id }` - The type of the tool. If type is `function`, the function name must be set + - `file_id: optional string` - - `"function"` + The ID of the file that was generated. - - `"code_interpreter"` + - `start_index: optional number` - - `"file_search"` + - `text: optional string` - - `function: optional AssistantToolChoiceFunction` + The text in the message content that needs to be replaced. - - `name: string` + - `value: optional string` - The name of the function to call. + The data that makes up the text. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` +### Text Delta Block - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. +- `TextDeltaBlock object { index, type, text }` - - `CodeInterpreterTool object { type }` + The text content that is part of a message. - - `type: "code_interpreter"` + - `index: number` - The type of tool being defined: `code_interpreter` + The index of the content part in the message. - - `"code_interpreter"` + - `type: "text"` - - `FileSearchTool object { type, file_search }` + Always `text`. - - `type: "file_search"` + - `"text"` - The type of tool being defined: `file_search` + - `text: optional TextDelta` - - `"file_search"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `file_search: optional object { max_num_results, ranking_options }` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - Overrides for the file search tool. + 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. - - `max_num_results: optional number` + - `index: number` - 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. + The index of the annotation in the text content part. - 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. + - `type: "file_citation"` - - `ranking_options: optional object { score_threshold, ranker }` + Always `file_citation`. - 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. + - `"file_citation"` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `end_index: optional number` - - `score_threshold: number` + - `file_citation: optional object { file_id, quote }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `file_id: optional string` - - `ranker: optional "auto" or "default_2024_08_21"` + The ID of the specific File the citation is from. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `quote: optional string` - - `"auto"` + The specific quote in the file. - - `"default_2024_08_21"` + - `start_index: optional number` - - `FunctionTool object { function, type }` + - `text: optional string` - - `function: FunctionDefinition` + The text in the message content that needs to be replaced. - - `name: string` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - 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. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `description: optional string` + - `index: number` - A description of what the function does, used by the model to choose when and how to call the function. + The index of the annotation in the text content part. - - `parameters: optional FunctionParameters` + - `type: "file_path"` - 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. + Always `file_path`. - Omitting `parameters` defines a function with an empty parameter list. + - `"file_path"` - - `strict: optional boolean` + - `end_index: optional number` - 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). + - `file_path: optional object { file_id }` - - `type: "function"` + - `file_id: optional string` - The type of tool being defined: `function` + The ID of the file that was generated. - - `"function"` + - `start_index: optional number` - - `truncation_strategy: object { type, last_messages }` + - `text: optional string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The text in the message content that needs to be replaced. - - `type: "auto" or "last_messages"` + - `value: optional string` - 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`. + The data that makes up the text. - - `"auto"` +# Runs - - `"last_messages"` +## Cancel a run - - `last_messages: optional number` +**post** `/threads/{thread_id}/runs/{run_id}/cancel` - The number of most recent messages from the thread when constructing the context for the run. +Cancels a run that is `in_progress`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` +### Path Parameters - 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.). +- `thread_id: string` - - `completion_tokens: number` +- `run_id: string` - Number of completion tokens used over the course of the run. +### Returns - - `prompt_tokens: number` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - Number of prompt tokens used over the course of the run. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `total_tokens: number` + - `id: string` - Total number of tokens used (prompt + completion). + The identifier, which can be referenced in API endpoints. - - `temperature: optional number` + - `assistant_id: string` - The sampling temperature used for this run. If not set, defaults to 1. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `top_p: optional number` + - `cancelled_at: number` - The nucleus sampling value used for this run. If not set, defaults to 1. + The Unix timestamp (in seconds) for when the run was cancelled. -### Example + - `completed_at: number` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/submit_tool_outputs \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "tool_outputs": [ - {} - ] - }' -``` + The Unix timestamp (in seconds) for when the run was completed. -#### Response + - `created_at: number` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + The Unix timestamp (in seconds) for when the run was created. -### Example + - `expires_at: number` -```http -curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ] - }' -``` + The Unix timestamp (in seconds) for when the run will expire. -#### Response - -```json -{ - "id": "run_123", - "object": "thread.run", - "created_at": 1699075592, - "assistant_id": "asst_123", - "thread_id": "thread_123", - "status": "queued", - "started_at": 1699075592, - "expires_at": 1699076192, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "tools": [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } - }, - "required": ["location"] - } - } - } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` - -### Streaming - -```http -curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ], - "stream": true - }' -``` - -#### Response - -```json -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} - -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - -event: thread.run.step.created -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - -event: thread.run.step.in_progress -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - -event: thread.message.created -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - -event: thread.message.in_progress -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} - -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} - -... - -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} - -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - -event: thread.message.completed -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} - -event: thread.run.step.completed -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} - -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - -event: done -data: [DONE] -``` - -## Cancel a run - -**post** `/threads/{thread_id}/runs/{run_id}/cancel` - -Cancels a run that is `in_progress`. - -### Path Parameters - -- `thread_id: string` - -- `run_id: string` - -### Returns - -- `Run object { id, assistant_id, cancelled_at, 24 more }` - - Represents an execution run on a [thread](/docs/api-reference/threads). - - - `id: string` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: number` - - The Unix timestamp (in seconds) for when the run was created. - - - `expires_at: number` - - The Unix timestamp (in seconds) for when the run will expire. - - - `failed_at: number` + - `failed_at: number` The Unix timestamp (in seconds) for when the run failed. @@ -6257,176 +5587,310 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ } ``` -## Domain Types +## Create run -### Required Action Function Tool Call +**post** `/threads/{thread_id}/runs` -- `RequiredActionFunctionToolCall object { id, function, type }` +Create a run. - Tool call objects +### Path Parameters - - `id: string` +- `thread_id: string` - 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. +### Query Parameters - - `function: object { arguments, name }` +- `include: optional array of RunStepInclude` - The function definition. + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - `arguments: string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The arguments that the model expects you to pass to the function. + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `name: string` +### Body Parameters - The name of the function. +- `assistant_id: string` - - `type: "function"` + The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. - The type of tool call the output is required for. For now, this is always `function`. +- `additional_instructions: optional string` - - `"function"` + 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. -### Run +- `additional_messages: optional array of object { content, role, attachments, metadata }` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + Adds additional messages to the thread before creating the run. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `id: string` + The text contents of the message. - The identifier, which can be referenced in API endpoints. + - `TextContent = string` - - `assistant_id: string` + The text contents of the message. - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `cancelled_at: number` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). - The Unix timestamp (in seconds) for when the run was cancelled. + - `ImageFileContentBlock object { image_file, type }` - - `completed_at: number` + References an image [File](/docs/api-reference/files) in the content of a message. - The Unix timestamp (in seconds) for when the run was completed. + - `image_file: ImageFile` - - `created_at: number` + - `file_id: string` - The Unix timestamp (in seconds) for when the run was created. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `expires_at: number` + - `detail: optional "auto" or "low" or "high"` - The Unix timestamp (in seconds) for when the run will expire. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `failed_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run failed. + - `"low"` - - `incomplete_details: object { reason }` + - `"high"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: "image_file"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + Always `image_file`. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"image_file"` - - `"max_completion_tokens"` + - `ImageURLContentBlock object { image_url, type }` - - `"max_prompt_tokens"` + References an image URL in the content of a message. - - `instructions: string` + - `image_url: ImageURL` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `url: string` - - `last_error: object { code, message }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The last error associated with this run. Will be `null` if there are no errors. + - `detail: optional "auto" or "low" or "high"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"auto"` - - `"server_error"` + - `"low"` - - `"rate_limit_exceeded"` + - `"high"` - - `"invalid_prompt"` + - `type: "image_url"` - - `message: string` + The type of the content part. - A human-readable description of the error. + - `"image_url"` - - `max_completion_tokens: number` + - `TextContentBlockParam object { text, type }` - The maximum number of completion tokens specified to have been used over the course of the run. + The text content that is part of a message. - - `max_prompt_tokens: number` + - `text: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + Text content to be sent to the model - - `metadata: Metadata` + - `type: "text"` - 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. + Always `text`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"text"` - - `model: string` + - `role: "user" or "assistant"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + The role of the entity that is creating the message. Allowed values include: - - `object: "thread.run"` + - `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. - The object type, which is always `thread.run`. + - `"user"` - - `"thread.run"` + - `"assistant"` - - `parallel_tool_calls: boolean` + - `attachments: optional array of object { file_id, tools }` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + A list of files attached to the message, and the tools they should be added to. - - `required_action: object { submit_tool_outputs, type }` + - `file_id: optional string` - Details on the action required to continue the run. Will be `null` if no action is required. + The ID of the file to attach to the message. - - `submit_tool_outputs: object { tool_calls }` + - `tools: optional array of CodeInterpreterTool or object { type }` - Details on the tool outputs needed for this run to continue. + The tools to add this file to. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `CodeInterpreterTool object { type }` - A list of the relevant tool calls. + - `type: "code_interpreter"` - - `id: string` + The type of tool being defined: `code_interpreter` - 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. + - `"code_interpreter"` - - `function: object { arguments, name }` + - `FileSearchTool object { type }` - The function definition. + - `type: "file_search"` - - `arguments: string` + The type of tool being defined: `file_search` - The arguments that the model expects you to pass to the function. + - `"file_search"` - - `name: string` + - `metadata: optional Metadata` - The name of the function. + 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. - - `type: "function"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of tool call the output is required for. For now, this is always `function`. +- `instructions: optional string` - - `"function"` + Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - - `type: "submit_tool_outputs"` +- `max_completion_tokens: optional number` - For now, this is always `submit_tool_outputs`. + 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. - - `"submit_tool_outputs"` +- `max_prompt_tokens: optional number` - - `response_format: AssistantResponseFormatOption` + 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. + +- `metadata: optional 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. + +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + + The ID of the [Model](/docs/api-reference/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. + + - `string` + + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + + The ID of the [Model](/docs/api-reference/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. + + - `"gpt-5"` + + - `"gpt-5-mini"` + + - `"gpt-5-nano"` + + - `"gpt-5-2025-08-07"` + + - `"gpt-5-mini-2025-08-07"` + + - `"gpt-5-nano-2025-08-07"` + + - `"gpt-4.1"` + + - `"gpt-4.1-mini"` + + - `"gpt-4.1-nano"` + + - `"gpt-4.1-2025-04-14"` + + - `"gpt-4.1-mini-2025-04-14"` + + - `"gpt-4.1-nano-2025-04-14"` + + - `"o3-mini"` + + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4.5-preview"` + + - `"gpt-4.5-preview-2025-02-27"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + +- `parallel_tool_calls: optional boolean` + + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + +- `reasoning_effort: optional ReasoningEffort` + + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://platform.openai.com/docs/guides/reasoning) + for model-specific support. + + - `"none"` + + - `"minimal"` + + - `"low"` + + - `"medium"` + + - `"high"` + + - `"xhigh"` + + - `"max"` + +- `response_format: optional AssistantResponseFormatOption` 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`. @@ -6503,37 +5967,15 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ - `"json_schema"` - - `started_at: number` - - The Unix timestamp (in seconds) for when the run was started. - - - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - - `"queued"` - - - `"in_progress"` - - - `"requires_action"` - - - `"cancelling"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"incomplete"` +- `stream: optional boolean` - - `"expired"` + 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. - - `thread_id: string` +- `temperature: optional number` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + 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. - - `tool_choice: AssistantToolChoiceOption` +- `tool_choice: optional 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. @@ -6571,18 +6013,12 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ The name of the function to call. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - `CodeInterpreterTool object { type }` - - `type: "code_interpreter"` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - `FileSearchTool object { type, file_search }` - `type: "file_search"` @@ -6647,7 +6083,13 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ - `"function"` - - `truncation_strategy: object { type, last_messages }` +- `top_p: optional number` + + 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. + +- `truncation_strategy: optional object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -6663,3452 +6105,4023 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ The number of most recent messages from the thread when constructing the context for the run. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` +### Returns - 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.). +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `completion_tokens: number` + Represents an execution run on a [thread](/docs/api-reference/threads). - Number of completion tokens used over the course of the run. + - `id: string` - - `prompt_tokens: number` + The identifier, which can be referenced in API endpoints. - Number of prompt tokens used over the course of the run. + - `assistant_id: string` - - `total_tokens: number` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - Total number of tokens used (prompt + completion). + - `cancelled_at: number` - - `temperature: optional number` + The Unix timestamp (in seconds) for when the run was cancelled. - The sampling temperature used for this run. If not set, defaults to 1. + - `completed_at: number` - - `top_p: optional number` + The Unix timestamp (in seconds) for when the run was completed. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `created_at: number` -# Steps + The Unix timestamp (in seconds) for when the run was created. -## List run steps + - `expires_at: number` -**get** `/threads/{thread_id}/runs/{run_id}/steps` + The Unix timestamp (in seconds) for when the run will expire. -Returns a list of run steps belonging to a run. - -### Path Parameters - -- `thread_id: string` + - `failed_at: number` -- `run_id: string` + The Unix timestamp (in seconds) for when the run failed. -### Query Parameters + - `incomplete_details: object { reason }` -- `after: optional string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` -- `before: optional string` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `"max_completion_tokens"` -- `include: optional array of RunStepInclude` + - `"max_prompt_tokens"` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `instructions: string` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `last_error: object { code, message }` -- `limit: optional number` + The last error associated with this run. Will be `null` if there are no errors. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` -- `order: optional "asc" or "desc"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `"server_error"` - - `"asc"` + - `"rate_limit_exceeded"` - - `"desc"` + - `"invalid_prompt"` -### Returns + - `message: string` -- `data: array of RunStep` + A human-readable description of the error. - - `id: string` + - `max_completion_tokens: number` - The identifier of the run step, which can be referenced in API endpoints. + The maximum number of completion tokens specified to have been used over the course of the run. - - `assistant_id: string` + - `max_prompt_tokens: number` - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `cancelled_at: number` + - `metadata: Metadata` - The Unix timestamp (in seconds) for when the run step was cancelled. + 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. - - `completed_at: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The Unix timestamp (in seconds) for when the run step completed. + - `model: string` - - `created_at: number` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The Unix timestamp (in seconds) for when the run step was created. + - `object: "thread.run"` - - `expired_at: number` + The object type, which is always `thread.run`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"thread.run"` - - `failed_at: number` + - `parallel_tool_calls: boolean` - The Unix timestamp (in seconds) for when the run step failed. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `last_error: object { code, message }` + - `required_action: object { submit_tool_outputs, type }` - The last error associated with this run step. Will be `null` if there are no errors. + Details on the action required to continue the run. Will be `null` if no action is required. - - `code: "server_error" or "rate_limit_exceeded"` + - `submit_tool_outputs: object { tool_calls }` - One of `server_error` or `rate_limit_exceeded`. + Details on the tool outputs needed for this run to continue. - - `"server_error"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `"rate_limit_exceeded"` + A list of the relevant tool calls. - - `message: string` + - `id: string` - A human-readable description of the error. + 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. - - `metadata: Metadata` + - `function: object { arguments, name }` - 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. + The function definition. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `arguments: string` - - `object: "thread.run.step"` + The arguments that the model expects you to pass to the function. - The object type, which is always `thread.run.step`. + - `name: string` - - `"thread.run.step"` + The name of the function. - - `run_id: string` + - `type: "function"` - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + The type of tool call the output is required for. For now, this is always `function`. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `"function"` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "submit_tool_outputs"` - - `"in_progress"` + For now, this is always `submit_tool_outputs`. - - `"cancelled"` + - `"submit_tool_outputs"` - - `"failed"` + - `response_format: AssistantResponseFormatOption` - - `"completed"` + 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`. - - `"expired"` + 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). - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The details of the run step. + **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. - - `MessageCreationStepDetails object { message_creation, type }` + - `"auto"` - Details of the message creation by the run step. + `auto` is the default value - - `message_creation: object { message_id }` + - `"auto"` - - `message_id: string` + - `ResponseFormatText object { type }` - The ID of the message that was created by this run step. + Default response format. Used to generate text responses. - - `type: "message_creation"` + - `type: "text"` - Always `message_creation`. + The type of response format being defined. Always `text`. - - `"message_creation"` + - `"text"` - - `ToolCallsStepDetails object { tool_calls, type }` + - `ResponseFormatJSONObject object { type }` - Details of the tool call. + 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. - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `type: "json_object"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The type of response format being defined. Always `json_object`. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"json_object"` - Details of the Code Interpreter tool call the run step was involved in. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `id: string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The ID of the tool call. + - `json_schema: object { name, description, schema, strict }` - - `code_interpreter: object { input, outputs }` + Structured Outputs configuration options, including a JSON Schema. - The Code Interpreter tool call definition. + - `name: string` - - `input: string` + 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. - The input to the Code Interpreter tool call. + - `description: optional string` - - `outputs: array of object { logs, type } or object { image, type }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `schema: optional map[unknown]` - - `CodeInterpreterLogOutput object { logs, type }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Text output from the Code Interpreter tool call as part of a run step. + - `strict: optional boolean` - - `logs: string` + 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). - The text output from the Code Interpreter tool call. + - `type: "json_schema"` - - `type: "logs"` + The type of response format being defined. Always `json_schema`. - Always `logs`. + - `"json_schema"` - - `"logs"` + - `started_at: number` - - `CodeInterpreterImageOutput object { image, type }` + The Unix timestamp (in seconds) for when the run was started. - - `image: object { file_id }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `file_id: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The [file](/docs/api-reference/files) ID of the image. + - `"queued"` - - `type: "image"` + - `"in_progress"` - Always `image`. + - `"requires_action"` - - `"image"` + - `"cancelling"` - - `type: "code_interpreter"` + - `"cancelled"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"failed"` - - `"code_interpreter"` + - `"completed"` - - `FileSearchToolCall object { id, file_search, type }` + - `"incomplete"` - - `id: string` + - `"expired"` - The ID of the tool call object. + - `thread_id: string` - - `file_search: object { ranking_options, results }` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - For now, this is always going to be an empty object. + - `tool_choice: AssistantToolChoiceOption` - - `ranking_options: optional object { ranker, score_threshold }` + 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. - The ranking options for the file search. + - `"none" or "auto" or "required"` - - `ranker: "auto" or "default_2024_08_21"` + `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. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"none"` - `"auto"` - - `"default_2024_08_21"` + - `"required"` - - `score_threshold: number` + - `AssistantToolChoice object { type, function }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "function" or "code_interpreter" or "file_search"` - The results of the file search. + The type of the tool. If type is `function`, the function name must be set - - `file_id: string` + - `"function"` - The ID of the file that result was found in. + - `"code_interpreter"` - - `file_name: string` + - `"file_search"` - The name of the file that result was found in. + - `function: optional AssistantToolChoiceFunction` - - `score: number` + - `name: string` - The score of the result. All values must be a floating point number between 0 and 1. + The name of the function to call. - - `content: optional array of object { text, type }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The content of the result that was found. The content is only included if requested via the include query parameter. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `text: optional string` + - `CodeInterpreterTool object { type }` - The text content of the file. + - `type: "code_interpreter"` - - `type: optional "text"` + The type of tool being defined: `code_interpreter` - The type of the content. + - `"code_interpreter"` - - `"text"` + - `FileSearchTool object { type, file_search }` - `type: "file_search"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The type of tool being defined: `file_search` - `"file_search"` - - `FunctionToolCall object { id, function, type }` + - `file_search: optional object { max_num_results, ranking_options }` - - `id: string` + Overrides for the file search tool. - The ID of the tool call object. + - `max_num_results: optional number` - - `function: object { arguments, name, output }` + 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. - The definition of the function that was called. + 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. - - `arguments: string` + - `ranking_options: optional object { score_threshold, ranker }` - The arguments passed to the function. + 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. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `FunctionTool object { function, type }` + + - `function: FunctionDefinition` - `name: string` - The name of the function. + 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. - - `output: string` + - `description: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional 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: optional boolean` + + 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). - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of tool being defined: `function` - `"function"` - - `type: "tool_calls"` - - Always `tool_calls`. + - `truncation_strategy: object { type, last_messages }` - - `"tool_calls"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `thread_id: string` + - `type: "auto" or "last_messages"` - The ID of the [thread](/docs/api-reference/threads) that was run. + 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`. - - `type: "message_creation" or "tool_calls"` + - `"auto"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"last_messages"` - - `"message_creation"` + - `last_messages: optional number` - - `"tool_calls"` + The number of most recent messages from the thread when constructing the context for the run. - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + 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: number` - Number of completion tokens used over the course of the run step. + Number of completion tokens used over the course of the run. - `prompt_tokens: number` - Number of prompt tokens used over the course of the run step. + Number of prompt tokens used over the course of the run. - `total_tokens: number` Total number of tokens used (prompt + completion). -- `first_id: string` + - `temperature: optional number` -- `has_more: boolean` + The sampling temperature used for this run. If not set, defaults to 1. -- `last_id: string` + - `top_p: optional number` -- `object: string` + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ + -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "assistant_id": "assistant_id", + "temperature": 1, + "top_p": 1 + }' ``` #### Response ```json { - "data": [ - { "id": "id", "assistant_id": "assistant_id", "cancelled_at": 0, "completed_at": 0, "created_at": 0, - "expired_at": 0, + "expires_at": 0, "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", "last_error": { "code": "server_error", "message": "message" }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, "metadata": { "foo": "string" }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" }, - "type": "message_creation" + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" }, + "response_format": "auto", + "started_at": 0, + "status": "queued", "thread_id": "thread_id", - "type": "message_creation", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, "usage": { "completion_tokens": 0, "prompt_tokens": 0, "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" + }, + "temperature": 0, + "top_p": 0 } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ +curl https://api.openai.com/v1/threads/thread_abc123/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123" + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", + "status": "queued", + "started_at": 1699063290, + "expires_at": null, "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, "failed_at": null, + "completed_at": 1699063291, "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" - } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" } ], - "first_id": "step_abc123", - "last_id": "step_abc456", - "has_more": false + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } ``` -## Retrieve run step - -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` +### Streaming -Retrieves a run step. +```http +curl https://api.openai.com/v1/threads/thread_123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "stream": true + }' +``` -### Path Parameters +#### Response -- `thread_id: string` +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} -- `run_id: string` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} -- `step_id: string` +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} -### Query Parameters +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} -- `include: optional array of RunStepInclude` +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `"step_details.tool_calls[*].file_search.results[*].content"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} -### Returns +... -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - Represents a step in execution of a run. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - - `id: string` +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} - The identifier of the run step, which can be referenced in API endpoints. +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - `assistant_id: string` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. +event: done +data: [DONE] +``` - - `cancelled_at: number` +### Streaming with Functions - The Unix timestamp (in seconds) for when the run step was cancelled. +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "stream": true + }' +``` - - `completed_at: number` +#### Response - The Unix timestamp (in seconds) for when the run step completed. +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `created_at: number` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - The Unix timestamp (in seconds) for when the run step was created. +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `expired_at: number` +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - - `failed_at: number` +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - The Unix timestamp (in seconds) for when the run step failed. +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `last_error: object { code, message }` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - The last error associated with this run step. Will be `null` if there are no errors. +... - - `code: "server_error" or "rate_limit_exceeded"` +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} - One of `server_error` or `rate_limit_exceeded`. +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - - `"server_error"` +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} - - `"rate_limit_exceeded"` +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - `message: string` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - A human-readable description of the error. +event: done +data: [DONE] +``` - - `metadata: Metadata` +## List runs - 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. +**get** `/threads/{thread_id}/runs` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +Returns a list of runs belonging to a thread. - - `object: "thread.run.step"` +### Path Parameters - The object type, which is always `thread.run.step`. +- `thread_id: string` - - `"thread.run.step"` +### Query Parameters - - `run_id: string` +- `after: optional string` - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` +- `before: optional string` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `"in_progress"` +- `limit: optional number` - - `"cancelled"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `"failed"` +- `order: optional "asc" or "desc"` - - `"completed"` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `"expired"` + - `"asc"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"desc"` - The details of the run step. +### Returns - - `MessageCreationStepDetails object { message_creation, type }` +- `data: array of Run` - Details of the message creation by the run step. + - `id: string` - - `message_creation: object { message_id }` + The identifier, which can be referenced in API endpoints. - - `message_id: string` + - `assistant_id: string` - The ID of the message that was created by this run step. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `type: "message_creation"` + - `cancelled_at: number` - Always `message_creation`. + The Unix timestamp (in seconds) for when the run was cancelled. - - `"message_creation"` + - `completed_at: number` - - `ToolCallsStepDetails object { tool_calls, type }` + The Unix timestamp (in seconds) for when the run was completed. - Details of the tool call. + - `created_at: number` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + The Unix timestamp (in seconds) for when the run was created. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `expires_at: number` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + The Unix timestamp (in seconds) for when the run will expire. - Details of the Code Interpreter tool call the run step was involved in. + - `failed_at: number` - - `id: string` + The Unix timestamp (in seconds) for when the run failed. - The ID of the tool call. + - `incomplete_details: object { reason }` - - `code_interpreter: object { input, outputs }` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The Code Interpreter tool call definition. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `input: string` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The input to the Code Interpreter tool call. + - `"max_completion_tokens"` - - `outputs: array of object { logs, type } or object { image, type }` + - `"max_prompt_tokens"` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `instructions: string` - - `CodeInterpreterLogOutput object { logs, type }` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - Text output from the Code Interpreter tool call as part of a run step. + - `last_error: object { code, message }` - - `logs: string` + The last error associated with this run. Will be `null` if there are no errors. - The text output from the Code Interpreter tool call. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `type: "logs"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - Always `logs`. + - `"server_error"` - - `"logs"` + - `"rate_limit_exceeded"` - - `CodeInterpreterImageOutput object { image, type }` + - `"invalid_prompt"` - - `image: object { file_id }` + - `message: string` - - `file_id: string` + A human-readable description of the error. - The [file](/docs/api-reference/files) ID of the image. + - `max_completion_tokens: number` - - `type: "image"` + The maximum number of completion tokens specified to have been used over the course of the run. - Always `image`. + - `max_prompt_tokens: number` - - `"image"` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `type: "code_interpreter"` + - `metadata: Metadata` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + 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. - - `"code_interpreter"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `FileSearchToolCall object { id, file_search, type }` + - `model: string` - - `id: string` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The ID of the tool call object. + - `object: "thread.run"` - - `file_search: object { ranking_options, results }` + The object type, which is always `thread.run`. - For now, this is always going to be an empty object. + - `"thread.run"` - - `ranking_options: optional object { ranker, score_threshold }` + - `parallel_tool_calls: boolean` - The ranking options for the file search. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `ranker: "auto" or "default_2024_08_21"` + - `required_action: object { submit_tool_outputs, type }` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Details on the action required to continue the run. Will be `null` if no action is required. - - `"auto"` + - `submit_tool_outputs: object { tool_calls }` - - `"default_2024_08_21"` + Details on the tool outputs needed for this run to continue. - - `score_threshold: number` + - `tool_calls: array of RequiredActionFunctionToolCall` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + A list of the relevant tool calls. - - `results: optional array of object { file_id, file_name, score, content }` + - `id: string` - The results of the file search. + 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. - - `file_id: string` + - `function: object { arguments, name }` - The ID of the file that result was found in. + The function definition. - - `file_name: string` + - `arguments: string` - The name of the file that result was found in. + The arguments that the model expects you to pass to the function. - - `score: number` + - `name: string` - The score of the result. All values must be a floating point number between 0 and 1. + The name of the function. - - `content: optional array of object { text, type }` + - `type: "function"` - The content of the result that was found. The content is only included if requested via the include query parameter. + The type of tool call the output is required for. For now, this is always `function`. - - `text: optional string` + - `"function"` - The text content of the file. + - `type: "submit_tool_outputs"` - - `type: optional "text"` + For now, this is always `submit_tool_outputs`. - The type of the content. + - `"submit_tool_outputs"` - - `"text"` + - `response_format: AssistantResponseFormatOption` - - `type: "file_search"` + 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`. - The type of tool call. This is always going to be `file_search` for this type of tool call. + 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). - - `"file_search"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `FunctionToolCall object { id, function, type }` + **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. - - `id: string` + - `"auto"` - The ID of the tool call object. + `auto` is the default value - - `function: object { arguments, name, output }` + - `"auto"` - The definition of the function that was called. + - `ResponseFormatText object { type }` - - `arguments: string` + Default response format. Used to generate text responses. - The arguments passed to the function. + - `type: "text"` - - `name: string` + The type of response format being defined. Always `text`. - The name of the function. + - `"text"` - - `output: string` + - `ResponseFormatJSONObject object { type }` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + 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: "function"` + - `type: "json_object"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of response format being defined. Always `json_object`. - - `"function"` + - `"json_object"` - - `type: "tool_calls"` + - `ResponseFormatJSONSchema object { json_schema, type }` - Always `tool_calls`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"tool_calls"` + - `json_schema: object { name, description, schema, strict }` - - `thread_id: string` + Structured Outputs configuration options, including a JSON Schema. - The ID of the [thread](/docs/api-reference/threads) that was run. + - `name: string` - - `type: "message_creation" or "tool_calls"` + 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. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `description: optional string` - - `"message_creation"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"tool_calls"` + - `schema: optional map[unknown]` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `strict: optional boolean` - - `completion_tokens: number` + 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). - Number of completion tokens used over the course of the run step. + - `type: "json_schema"` - - `prompt_tokens: number` + The type of response format being defined. Always `json_schema`. - Number of prompt tokens used over the course of the run step. + - `"json_schema"` - - `total_tokens: number` + - `started_at: number` - Total number of tokens used (prompt + completion). + The Unix timestamp (in seconds) for when the run was started. -### Example + - `status: "queued" or "in_progress" or "requires_action" or 6 more` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps/$STEP_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. -#### Response + - `"queued"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } -} -``` + - `"in_progress"` -### Example + - `"requires_action"` -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `"cancelling"` -#### Response + - `"cancelled"` -```json -{ - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", - "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, - "failed_at": null, - "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" - } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } -} -``` + - `"failed"` -## Domain Types + - `"completed"` -### Code Interpreter Logs + - `"incomplete"` -- `CodeInterpreterLogs object { index, type, logs }` + - `"expired"` - Text output from the Code Interpreter tool call as part of a run step. + - `thread_id: string` - - `index: number` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - The index of the output in the outputs array. + - `tool_choice: AssistantToolChoiceOption` - - `type: "logs"` + 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. - Always `logs`. + - `"none" or "auto" or "required"` - - `"logs"` + `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. - - `logs: optional string` + - `"none"` - The text output from the Code Interpreter tool call. + - `"auto"` -### Code Interpreter Output Image + - `"required"` -- `CodeInterpreterOutputImage object { index, type, image }` + - `AssistantToolChoice object { type, function }` - - `index: number` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The index of the output in the outputs array. + - `type: "function" or "code_interpreter" or "file_search"` - - `type: "image"` + The type of the tool. If type is `function`, the function name must be set - Always `image`. + - `"function"` - - `"image"` + - `"code_interpreter"` - - `image: optional object { file_id }` + - `"file_search"` - - `file_id: optional string` + - `function: optional AssistantToolChoiceFunction` - The [file](/docs/api-reference/files) ID of the image. + - `name: string` -### Code Interpreter Tool Call + The name of the function to call. -- `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - Details of the Code Interpreter tool call the run step was involved in. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `id: string` + - `CodeInterpreterTool object { type }` - The ID of the tool call. + - `type: "code_interpreter"` - - `code_interpreter: object { input, outputs }` - - The Code Interpreter tool call definition. - - - `input: string` - - The input to the Code Interpreter tool call. - - - `outputs: array of object { logs, type } or object { image, type }` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `CodeInterpreterLogOutput object { logs, type }` - - Text output from the Code Interpreter tool call as part of a run step. - - - `logs: string` - - The text output from the Code Interpreter tool call. - - - `type: "logs"` - - Always `logs`. - - - `"logs"` - - - `CodeInterpreterImageOutput object { image, type }` - - - `image: object { file_id }` - - - `file_id: string` - - The [file](/docs/api-reference/files) ID of the image. - - - `type: "image"` - - Always `image`. - - - `"image"` - - - `type: "code_interpreter"` - - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The type of tool being defined: `code_interpreter` - `"code_interpreter"` -### Code Interpreter Tool Call Delta - -- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - - Details of the Code Interpreter tool call the run step was involved in. - - - `index: number` - - The index of the tool call in the tool calls array. + - `FileSearchTool object { type, file_search }` - - `type: "code_interpreter"` + - `type: "file_search"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The type of tool being defined: `file_search` - - `"code_interpreter"` + - `"file_search"` - - `id: optional string` + - `file_search: optional object { max_num_results, ranking_options }` - The ID of the tool call. + Overrides for the file search tool. - - `code_interpreter: optional object { input, outputs }` + - `max_num_results: optional number` - The Code Interpreter tool call definition. + 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. - - `input: optional string` + 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. - The input to the Code Interpreter tool call. + - `ranking_options: optional object { score_threshold, ranker }` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + 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. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `CodeInterpreterLogs object { index, type, logs }` + - `score_threshold: number` - Text output from the Code Interpreter tool call as part of a run step. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `index: number` + - `ranker: optional "auto" or "default_2024_08_21"` - The index of the output in the outputs array. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: "logs"` + - `"auto"` - Always `logs`. + - `"default_2024_08_21"` - - `"logs"` + - `FunctionTool object { function, type }` - - `logs: optional string` + - `function: FunctionDefinition` - The text output from the Code Interpreter tool call. + - `name: string` - - `CodeInterpreterOutputImage object { index, type, image }` + 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. - - `index: number` + - `description: optional string` - The index of the output in the outputs array. + A description of what the function does, used by the model to choose when and how to call the function. - - `type: "image"` + - `parameters: optional FunctionParameters` - Always `image`. + 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. - - `"image"` + Omitting `parameters` defines a function with an empty parameter list. - - `image: optional object { file_id }` + - `strict: optional boolean` - - `file_id: optional string` + 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). - The [file](/docs/api-reference/files) ID of the image. + - `type: "function"` -### File Search Tool Call + The type of tool being defined: `function` -- `FileSearchToolCall object { id, file_search, type }` + - `"function"` - - `id: string` + - `truncation_strategy: object { type, last_messages }` - The ID of the tool call object. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `file_search: object { ranking_options, results }` + - `type: "auto" or "last_messages"` - For now, this is always going to be an empty object. + 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`. - - `ranking_options: optional object { ranker, score_threshold }` + - `"auto"` - The ranking options for the file search. + - `"last_messages"` - - `ranker: "auto" or "default_2024_08_21"` + - `last_messages: optional number` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The number of most recent messages from the thread when constructing the context for the run. - - `"auto"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"default_2024_08_21"` + 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.). - - `score_threshold: number` + - `completion_tokens: number` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Number of completion tokens used over the course of the run. - - `results: optional array of object { file_id, file_name, score, content }` + - `prompt_tokens: number` - The results of the file search. + Number of prompt tokens used over the course of the run. - - `file_id: string` + - `total_tokens: number` - The ID of the file that result was found in. + Total number of tokens used (prompt + completion). - - `file_name: string` + - `temperature: optional number` - The name of the file that result was found in. + The sampling temperature used for this run. If not set, defaults to 1. - - `score: number` + - `top_p: optional number` - The score of the result. All values must be a floating point number between 0 and 1. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `content: optional array of object { text, type }` +- `first_id: string` - The content of the result that was found. The content is only included if requested via the include query parameter. +- `has_more: boolean` - - `text: optional string` +- `last_id: string` - The text content of the file. +- `object: string` - - `type: optional "text"` +### Example - The type of the content. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"text"` +#### Response - - `type: "file_search"` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 + } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" +} +``` - The type of tool call. This is always going to be `file_search` for this type of tool call. +### Example - - `"file_search"` +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" +``` -### File Search Tool Call Delta +#### Response -- `FileSearchToolCallDelta object { file_search, index, type, id }` - - - `file_search: unknown` - - For now, this is always going to be an empty object. +```json +{ + "object": "list", + "data": [ + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + }, + { + "id": "run_abc456", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + ], + "first_id": "run_abc123", + "last_id": "run_abc456", + "has_more": false +} +``` - - `index: number` +## Retrieve run - The index of the tool call in the tool calls array. +**get** `/threads/{thread_id}/runs/{run_id}` - - `type: "file_search"` +Retrieves a run. - The type of tool call. This is always going to be `file_search` for this type of tool call. +### Path Parameters - - `"file_search"` +- `thread_id: string` - - `id: optional string` +- `run_id: string` - The ID of the tool call object. +### Returns -### Function Tool Call +- `Run object { id, assistant_id, cancelled_at, 24 more }` -- `FunctionToolCall object { id, function, type }` + Represents an execution run on a [thread](/docs/api-reference/threads). - `id: string` - The ID of the tool call object. + The identifier, which can be referenced in API endpoints. - - `function: object { arguments, name, output }` + - `assistant_id: string` - The definition of the function that was called. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `arguments: string` + - `cancelled_at: number` - The arguments passed to the function. + The Unix timestamp (in seconds) for when the run was cancelled. - - `name: string` + - `completed_at: number` - The name of the function. + The Unix timestamp (in seconds) for when the run was completed. - - `output: string` + - `created_at: number` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + The Unix timestamp (in seconds) for when the run was created. - - `type: "function"` + - `expires_at: number` - The type of tool call. This is always going to be `function` for this type of tool call. + The Unix timestamp (in seconds) for when the run will expire. - - `"function"` + - `failed_at: number` -### Function Tool Call Delta + The Unix timestamp (in seconds) for when the run failed. -- `FunctionToolCallDelta object { index, type, id, function }` + - `incomplete_details: object { reason }` - - `index: number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The index of the tool call in the tool calls array. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `type: "function"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The type of tool call. This is always going to be `function` for this type of tool call. + - `"max_completion_tokens"` - - `"function"` + - `"max_prompt_tokens"` - - `id: optional string` + - `instructions: string` - The ID of the tool call object. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `function: optional object { arguments, name, output }` + - `last_error: object { code, message }` - The definition of the function that was called. + The last error associated with this run. Will be `null` if there are no errors. - - `arguments: optional string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The arguments passed to the function. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `name: optional string` + - `"server_error"` - The name of the function. + - `"rate_limit_exceeded"` - - `output: optional string` + - `"invalid_prompt"` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + - `message: string` -### Message Creation Step Details + A human-readable description of the error. -- `MessageCreationStepDetails object { message_creation, type }` + - `max_completion_tokens: number` - Details of the message creation by the run step. + The maximum number of completion tokens specified to have been used over the course of the run. - - `message_creation: object { message_id }` + - `max_prompt_tokens: number` - - `message_id: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The ID of the message that was created by this run step. + - `metadata: Metadata` - - `type: "message_creation"` + 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. - Always `message_creation`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"message_creation"` + - `model: string` -### Run Step + The model that the [assistant](/docs/api-reference/assistants) used for this run. -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` + - `object: "thread.run"` - Represents a step in execution of a run. + The object type, which is always `thread.run`. - - `id: string` + - `"thread.run"` - The identifier of the run step, which can be referenced in API endpoints. + - `parallel_tool_calls: boolean` - - `assistant_id: string` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + - `required_action: object { submit_tool_outputs, type }` - - `cancelled_at: number` + Details on the action required to continue the run. Will be `null` if no action is required. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `submit_tool_outputs: object { tool_calls }` - - `completed_at: number` + Details on the tool outputs needed for this run to continue. - The Unix timestamp (in seconds) for when the run step completed. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `created_at: number` + A list of the relevant tool calls. - The Unix timestamp (in seconds) for when the run step was created. + - `id: string` - - `expired_at: number` + 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. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `function: object { arguments, name }` - - `failed_at: number` + The function definition. - The Unix timestamp (in seconds) for when the run step failed. + - `arguments: string` - - `last_error: object { code, message }` + The arguments that the model expects you to pass to the function. - The last error associated with this run step. Will be `null` if there are no errors. + - `name: string` - - `code: "server_error" or "rate_limit_exceeded"` + The name of the function. - One of `server_error` or `rate_limit_exceeded`. + - `type: "function"` - - `"server_error"` + The type of tool call the output is required for. For now, this is always `function`. - - `"rate_limit_exceeded"` + - `"function"` - - `message: string` + - `type: "submit_tool_outputs"` - A human-readable description of the error. + For now, this is always `submit_tool_outputs`. - - `metadata: Metadata` + - `"submit_tool_outputs"` - 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. + - `response_format: AssistantResponseFormatOption` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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`. - - `object: "thread.run.step"` + 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). - The object type, which is always `thread.run.step`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"thread.run.step"` + **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. - - `run_id: string` + - `"auto"` - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + `auto` is the default value - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `"auto"` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `ResponseFormatText object { type }` - - `"in_progress"` + Default response format. Used to generate text responses. - - `"cancelled"` + - `type: "text"` - - `"failed"` + The type of response format being defined. Always `text`. - - `"completed"` + - `"text"` - - `"expired"` + - `ResponseFormatJSONObject object { type }` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + 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. - The details of the run step. + - `type: "json_object"` - - `MessageCreationStepDetails object { message_creation, type }` + The type of response format being defined. Always `json_object`. - Details of the message creation by the run step. + - `"json_object"` - - `message_creation: object { message_id }` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `message_id: string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The ID of the message that was created by this run step. + - `json_schema: object { name, description, schema, strict }` - - `type: "message_creation"` + Structured Outputs configuration options, including a JSON Schema. - Always `message_creation`. + - `name: string` - - `"message_creation"` + 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. - - `ToolCallsStepDetails object { tool_calls, type }` + - `description: optional string` - Details of the tool call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `schema: optional map[unknown]` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `strict: optional boolean` - Details of the Code Interpreter tool call the run step was involved in. + 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). - - `id: string` + - `type: "json_schema"` - The ID of the tool call. + The type of response format being defined. Always `json_schema`. - - `code_interpreter: object { input, outputs }` + - `"json_schema"` - The Code Interpreter tool call definition. + - `started_at: number` - - `input: string` + The Unix timestamp (in seconds) for when the run was started. - The input to the Code Interpreter tool call. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `outputs: array of object { logs, type } or object { image, type }` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `"queued"` - - `CodeInterpreterLogOutput object { logs, type }` + - `"in_progress"` - Text output from the Code Interpreter tool call as part of a run step. + - `"requires_action"` - - `logs: string` + - `"cancelling"` - The text output from the Code Interpreter tool call. + - `"cancelled"` - - `type: "logs"` + - `"failed"` - Always `logs`. + - `"completed"` - - `"logs"` + - `"incomplete"` - - `CodeInterpreterImageOutput object { image, type }` + - `"expired"` - - `image: object { file_id }` + - `thread_id: string` - - `file_id: string` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - The [file](/docs/api-reference/files) ID of the image. + - `tool_choice: AssistantToolChoiceOption` - - `type: "image"` + 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. - Always `image`. + - `"none" or "auto" or "required"` - - `"image"` + `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. - - `type: "code_interpreter"` + - `"none"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"auto"` - - `"code_interpreter"` + - `"required"` - - `FileSearchToolCall object { id, file_search, type }` + - `AssistantToolChoice object { type, function }` - - `id: string` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The ID of the tool call object. + - `type: "function" or "code_interpreter" or "file_search"` - - `file_search: object { ranking_options, results }` + The type of the tool. If type is `function`, the function name must be set - For now, this is always going to be an empty object. + - `"function"` - - `ranking_options: optional object { ranker, score_threshold }` + - `"code_interpreter"` - The ranking options for the file search. + - `"file_search"` - - `ranker: "auto" or "default_2024_08_21"` + - `function: optional AssistantToolChoiceFunction` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `name: string` - - `"auto"` + The name of the function to call. - - `"default_2024_08_21"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `score_threshold: number` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `CodeInterpreterTool object { type }` - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "code_interpreter"` - The results of the file search. + The type of tool being defined: `code_interpreter` - - `file_id: string` + - `"code_interpreter"` - The ID of the file that result was found in. + - `FileSearchTool object { type, file_search }` - - `file_name: string` + - `type: "file_search"` - The name of the file that result was found in. + The type of tool being defined: `file_search` - - `score: number` + - `"file_search"` - The score of the result. All values must be a floating point number between 0 and 1. + - `file_search: optional object { max_num_results, ranking_options }` - - `content: optional array of object { text, type }` + Overrides for the file search tool. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `max_num_results: optional number` - - `text: optional string` + 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. - The text content of the file. + 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. - - `type: optional "text"` + - `ranking_options: optional object { score_threshold, ranker }` - The type of the content. + 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. - - `"text"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "file_search"` + - `score_threshold: number` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"file_search"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `FunctionToolCall object { id, function, type }` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `id: string` + - `"auto"` - The ID of the tool call object. + - `"default_2024_08_21"` - - `function: object { arguments, name, output }` + - `FunctionTool object { function, type }` - The definition of the function that was called. + - `function: FunctionDefinition` - - `arguments: string` + - `name: string` - The arguments passed to the function. + 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. - - `name: string` + - `description: optional string` - The name of the function. + A description of what the function does, used by the model to choose when and how to call the function. - - `output: string` + - `parameters: optional FunctionParameters` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + 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: optional boolean` + + 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). - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of tool being defined: `function` - `"function"` - - `type: "tool_calls"` - - Always `tool_calls`. + - `truncation_strategy: object { type, last_messages }` - - `"tool_calls"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `thread_id: string` + - `type: "auto" or "last_messages"` - The ID of the [thread](/docs/api-reference/threads) that was run. + 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`. - - `type: "message_creation" or "tool_calls"` + - `"auto"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"last_messages"` - - `"message_creation"` + - `last_messages: optional number` - - `"tool_calls"` + The number of most recent messages from the thread when constructing the context for the run. - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + 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: number` - Number of completion tokens used over the course of the run step. + Number of completion tokens used over the course of the run. - `prompt_tokens: number` - Number of prompt tokens used over the course of the run step. + Number of prompt tokens used over the course of the run. - `total_tokens: number` Total number of tokens used (prompt + completion). -### Run Step Delta Event + - `temperature: optional number` -- `RunStepDeltaEvent object { id, delta, object }` + The sampling temperature used for this run. If not set, defaults to 1. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `top_p: optional number` - - `id: string` + The nucleus sampling value used for this run. If not set, defaults to 1. - The identifier of the run step, which can be referenced in API endpoints. +### Example - - `delta: object { step_details }` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The delta containing the fields that have changed on the run step. +#### Response - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - The details of the run step. +### Example - - `RunStepDeltaMessageDelta object { type, message_creation }` +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - Details of the message creation by the run step. +#### Response - - `type: "message_creation"` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - Always `message_creation`. +## Submit tool outputs to run - - `"message_creation"` +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - - `message_creation: optional object { message_id }` +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. - - `message_id: optional string` +### Path Parameters - The ID of the message that was created by this run step. +- `thread_id: string` - - `ToolCallDeltaObject object { type, tool_calls }` +- `run_id: string` - Details of the tool call. +### Body Parameters - - `type: "tool_calls"` +- `tool_outputs: array of object { output, tool_call_id }` - Always `tool_calls`. + A list of tools for which the outputs are being submitted. - - `"tool_calls"` + - `output: optional string` - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + The output of the tool call to be submitted to continue the run. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `tool_call_id: optional string` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - Details of the Code Interpreter tool call the run step was involved in. +- `stream: optional boolean` - - `index: number` + 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. - The index of the tool call in the tool calls array. +### Returns - - `type: "code_interpreter"` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"code_interpreter"` + - `id: string` - - `id: optional string` + The identifier, which can be referenced in API endpoints. - The ID of the tool call. + - `assistant_id: string` - - `code_interpreter: optional object { input, outputs }` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The Code Interpreter tool call definition. + - `cancelled_at: number` - - `input: optional string` + The Unix timestamp (in seconds) for when the run was cancelled. - The input to the Code Interpreter tool call. + - `completed_at: number` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + The Unix timestamp (in seconds) for when the run was completed. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `created_at: number` - - `CodeInterpreterLogs object { index, type, logs }` + The Unix timestamp (in seconds) for when the run was created. - Text output from the Code Interpreter tool call as part of a run step. + - `expires_at: number` - - `index: number` + The Unix timestamp (in seconds) for when the run will expire. - The index of the output in the outputs array. + - `failed_at: number` - - `type: "logs"` + The Unix timestamp (in seconds) for when the run failed. - Always `logs`. + - `incomplete_details: object { reason }` - - `"logs"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `logs: optional string` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The text output from the Code Interpreter tool call. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `CodeInterpreterOutputImage object { index, type, image }` + - `"max_completion_tokens"` - - `index: number` + - `"max_prompt_tokens"` - The index of the output in the outputs array. + - `instructions: string` - - `type: "image"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - Always `image`. + - `last_error: object { code, message }` - - `"image"` + The last error associated with this run. Will be `null` if there are no errors. - - `image: optional object { file_id }` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `file_id: optional string` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The [file](/docs/api-reference/files) ID of the image. + - `"server_error"` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `"rate_limit_exceeded"` - - `file_search: unknown` + - `"invalid_prompt"` - For now, this is always going to be an empty object. + - `message: string` - - `index: number` + A human-readable description of the error. - The index of the tool call in the tool calls array. + - `max_completion_tokens: number` - - `type: "file_search"` + The maximum number of completion tokens specified to have been used over the course of the run. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `max_prompt_tokens: number` - - `"file_search"` + The maximum number of prompt tokens specified to have been used over the course of the run. - - `id: optional string` + - `metadata: Metadata` - The ID of the tool call object. + 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. - - `FunctionToolCallDelta object { index, type, id, function }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `index: number` + - `model: string` - The index of the tool call in the tool calls array. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `type: "function"` + - `object: "thread.run"` - The type of tool call. This is always going to be `function` for this type of tool call. + The object type, which is always `thread.run`. - - `"function"` + - `"thread.run"` - - `id: optional string` + - `parallel_tool_calls: boolean` - The ID of the tool call object. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `function: optional object { arguments, name, output }` + - `required_action: object { submit_tool_outputs, type }` - The definition of the function that was called. + Details on the action required to continue the run. Will be `null` if no action is required. - - `arguments: optional string` + - `submit_tool_outputs: object { tool_calls }` - The arguments passed to the function. + Details on the tool outputs needed for this run to continue. - - `name: optional string` + - `tool_calls: array of RequiredActionFunctionToolCall` + + A list of the relevant tool calls. + + - `id: string` + + 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. + + - `function: object { arguments, name }` + + The function definition. + + - `arguments: string` + + The arguments that the model expects you to pass to the function. + + - `name: string` The name of the function. - - `output: optional string` + - `type: "function"` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + The type of tool call the output is required for. For now, this is always `function`. - - `object: "thread.run.step.delta"` + - `"function"` - The object type, which is always `thread.run.step.delta`. + - `type: "submit_tool_outputs"` - - `"thread.run.step.delta"` + For now, this is always `submit_tool_outputs`. -### Run Step Delta Message Delta + - `"submit_tool_outputs"` -- `RunStepDeltaMessageDelta object { type, message_creation }` + - `response_format: AssistantResponseFormatOption` - Details of the message creation by the run step. + 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`. - - `type: "message_creation"` + 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). - Always `message_creation`. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"message_creation"` + **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. - - `message_creation: optional object { message_id }` + - `"auto"` - - `message_id: optional string` + `auto` is the default value - The ID of the message that was created by this run step. + - `"auto"` -### Run Step Include + - `ResponseFormatText object { type }` -- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` + Default response format. Used to generate text responses. - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `type: "text"` -### Tool Call Delta Object + The type of response format being defined. Always `text`. -- `ToolCallDeltaObject object { type, tool_calls }` + - `"text"` - Details of the tool call. + - `ResponseFormatJSONObject object { type }` - - `type: "tool_calls"` + 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. - Always `tool_calls`. + - `type: "json_object"` - - `"tool_calls"` + The type of response format being defined. Always `json_object`. - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + - `"json_object"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - Details of the Code Interpreter tool call the run step was involved in. + - `json_schema: object { name, description, schema, strict }` - - `index: number` + Structured Outputs configuration options, including a JSON Schema. - The index of the tool call in the tool calls array. + - `name: string` - - `type: "code_interpreter"` + 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. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `description: optional string` - - `"code_interpreter"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `id: optional string` + - `schema: optional map[unknown]` - The ID of the tool call. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `code_interpreter: optional object { input, outputs }` + - `strict: optional boolean` - The Code Interpreter tool call definition. + 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). - - `input: optional string` + - `type: "json_schema"` - The input to the Code Interpreter tool call. + The type of response format being defined. Always `json_schema`. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `"json_schema"` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `started_at: number` - - `CodeInterpreterLogs object { index, type, logs }` + The Unix timestamp (in seconds) for when the run was started. - Text output from the Code Interpreter tool call as part of a run step. + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `index: number` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The index of the output in the outputs array. + - `"queued"` - - `type: "logs"` + - `"in_progress"` - Always `logs`. + - `"requires_action"` - - `"logs"` + - `"cancelling"` - - `logs: optional string` + - `"cancelled"` - The text output from the Code Interpreter tool call. + - `"failed"` - - `CodeInterpreterOutputImage object { index, type, image }` + - `"completed"` - - `index: number` + - `"incomplete"` - The index of the output in the outputs array. + - `"expired"` - - `type: "image"` + - `thread_id: string` - Always `image`. + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"image"` + - `tool_choice: AssistantToolChoiceOption` - - `image: optional object { file_id }` + 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. - - `file_id: optional string` + - `"none" or "auto" or "required"` - The [file](/docs/api-reference/files) ID of the image. + `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. - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `"none"` - - `file_search: unknown` + - `"auto"` - For now, this is always going to be an empty object. + - `"required"` - - `index: number` + - `AssistantToolChoice object { type, function }` - The index of the tool call in the tool calls array. + Specifies a tool the model should use. Use to force the model to call a specific tool. + + - `type: "function" or "code_interpreter" or "file_search"` + + The type of the tool. If type is `function`, the function name must be set + + - `"function"` + + - `"code_interpreter"` + + - `"file_search"` + + - `function: optional AssistantToolChoiceFunction` + + - `name: string` + + The name of the function to call. + + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + + - `CodeInterpreterTool object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `FileSearchTool object { type, file_search }` - `type: "file_search"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The type of tool being defined: `file_search` - `"file_search"` - - `id: optional string` + - `file_search: optional object { max_num_results, ranking_options }` - The ID of the tool call object. + Overrides for the file search tool. - - `FunctionToolCallDelta object { index, type, id, function }` + - `max_num_results: optional number` - - `index: number` + 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. - The index of the tool call in the tool calls array. + 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: optional object { score_threshold, ranker }` + + 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. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `FunctionTool object { function, type }` + + - `function: FunctionDefinition` + + - `name: string` + + 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. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional 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: optional boolean` + + 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). - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of tool being defined: `function` - `"function"` - - `id: optional string` + - `truncation_strategy: object { type, last_messages }` - The ID of the tool call object. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `function: optional object { arguments, name, output }` + - `type: "auto" or "last_messages"` - The definition of the function that was called. + 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`. - - `arguments: optional string` + - `"auto"` - The arguments passed to the function. + - `"last_messages"` - - `name: optional string` + - `last_messages: optional number` - The name of the function. + The number of most recent messages from the thread when constructing the context for the run. - - `output: optional string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + 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.). -### Tool Calls Step Details + - `completion_tokens: number` -- `ToolCallsStepDetails object { tool_calls, type }` + Number of completion tokens used over the course of the run. - Details of the tool call. + - `prompt_tokens: number` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + Number of prompt tokens used over the course of the run. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `total_tokens: number` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + Total number of tokens used (prompt + completion). - Details of the Code Interpreter tool call the run step was involved in. + - `temperature: optional number` - - `id: string` + The sampling temperature used for this run. If not set, defaults to 1. - The ID of the tool call. + - `top_p: optional number` + + The nucleus sampling value used for this run. If not set, defaults to 1. + +### Example + +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/submit_tool_outputs \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "tool_outputs": [ + {} + ] + }' +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` + +### Example + +```http +curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + }' +``` + +#### Response + +```json +{ + "id": "run_123", + "object": "thread.run", + "created_at": 1699075592, + "assistant_id": "asst_123", + "thread_id": "thread_123", + "status": "queued", + "started_at": 1699075592, + "expires_at": 1699076192, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` + +### Streaming + +```http +curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + "stream": true + }' +``` + +#### Response + +```json +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} + +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `code_interpreter: object { input, outputs }` +event: thread.run.step.created +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - The Code Interpreter tool call definition. +event: thread.run.step.in_progress +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - `input: string` +event: thread.message.created +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - The input to the Code Interpreter tool call. +event: thread.message.in_progress +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `outputs: array of object { logs, type } or object { image, type }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} - - `CodeInterpreterLogOutput object { logs, type }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} - Text output from the Code Interpreter tool call as part of a run step. +... - - `logs: string` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} - The text output from the Code Interpreter tool call. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - - `type: "logs"` +event: thread.message.completed +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} - Always `logs`. +event: thread.run.step.completed +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} - - `"logs"` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `CodeInterpreterImageOutput object { image, type }` +event: done +data: [DONE] +``` - - `image: object { file_id }` +## Modify run - - `file_id: string` +**post** `/threads/{thread_id}/runs/{run_id}` - The [file](/docs/api-reference/files) ID of the image. +Modifies a run. - - `type: "image"` +### Path Parameters - Always `image`. +- `thread_id: string` - - `"image"` +- `run_id: string` - - `type: "code_interpreter"` +### Body Parameters - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. +- `metadata: optional Metadata` - - `"code_interpreter"` + 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. - - `FileSearchToolCall object { id, file_search, type }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: string` +### Returns - The ID of the tool call object. +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `file_search: object { ranking_options, results }` + Represents an execution run on a [thread](/docs/api-reference/threads). - For now, this is always going to be an empty object. + - `id: string` - - `ranking_options: optional object { ranker, score_threshold }` + The identifier, which can be referenced in API endpoints. - The ranking options for the file search. + - `assistant_id: string` - - `ranker: "auto" or "default_2024_08_21"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `cancelled_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"default_2024_08_21"` + - `completed_at: number` - - `score_threshold: number` + The Unix timestamp (in seconds) for when the run was completed. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `created_at: number` - - `results: optional array of object { file_id, file_name, score, content }` + The Unix timestamp (in seconds) for when the run was created. - The results of the file search. + - `expires_at: number` - - `file_id: string` + The Unix timestamp (in seconds) for when the run will expire. - The ID of the file that result was found in. + - `failed_at: number` - - `file_name: string` + The Unix timestamp (in seconds) for when the run failed. - The name of the file that result was found in. + - `incomplete_details: object { reason }` - - `score: number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The score of the result. All values must be a floating point number between 0 and 1. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `content: optional array of object { text, type }` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"max_completion_tokens"` - - `text: optional string` + - `"max_prompt_tokens"` - The text content of the file. + - `instructions: string` - - `type: optional "text"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - The type of the content. + - `last_error: object { code, message }` - - `"text"` + The last error associated with this run. Will be `null` if there are no errors. - - `type: "file_search"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"file_search"` + - `"server_error"` - - `FunctionToolCall object { id, function, type }` + - `"rate_limit_exceeded"` - - `id: string` + - `"invalid_prompt"` - The ID of the tool call object. + - `message: string` - - `function: object { arguments, name, output }` + A human-readable description of the error. - The definition of the function that was called. + - `max_completion_tokens: number` - - `arguments: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The arguments passed to the function. + - `max_prompt_tokens: number` - - `name: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The name of the function. + - `metadata: Metadata` - - `output: string` + 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. - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "function"` + - `model: string` - The type of tool call. This is always going to be `function` for this type of tool call. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"function"` + - `object: "thread.run"` - - `type: "tool_calls"` + The object type, which is always `thread.run`. - Always `tool_calls`. + - `"thread.run"` - - `"tool_calls"` + - `parallel_tool_calls: boolean` -# Messages + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. -## List messages + - `required_action: object { submit_tool_outputs, type }` -**get** `/threads/{thread_id}/messages` + Details on the action required to continue the run. Will be `null` if no action is required. -Returns a list of messages for a given thread. + - `submit_tool_outputs: object { tool_calls }` -### Path Parameters + Details on the tool outputs needed for this run to continue. -- `thread_id: string` + - `tool_calls: array of RequiredActionFunctionToolCall` -### Query Parameters + A list of the relevant tool calls. -- `after: optional string` + - `id: string` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + 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. -- `before: optional string` + - `function: object { arguments, name }` - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + The function definition. -- `limit: optional number` + - `arguments: string` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The arguments that the model expects you to pass to the function. -- `order: optional "asc" or "desc"` + - `name: string` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The name of the function. - - `"asc"` + - `type: "function"` - - `"desc"` + The type of tool call the output is required for. For now, this is always `function`. -- `run_id: optional string` + - `"function"` - Filter messages by the run ID that generated them. + - `type: "submit_tool_outputs"` -### Returns + For now, this is always `submit_tool_outputs`. -- `data: array of Message` + - `"submit_tool_outputs"` - - `id: string` + - `response_format: AssistantResponseFormatOption` - The identifier, which can be referenced in API endpoints. + 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`. - - `assistant_id: string` + 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). - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `attachments: array of object { file_id, tools }` + **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. - A list of files attached to the message, and the tools they were added to. + - `"auto"` - - `file_id: optional string` + `auto` is the default value - The ID of the file to attach to the message. + - `"auto"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `ResponseFormatText object { type }` - The tools to add this file to. + Default response format. Used to generate text responses. - - `CodeInterpreterTool object { type }` + - `type: "text"` - - `type: "code_interpreter"` + The type of response format being defined. Always `text`. - The type of tool being defined: `code_interpreter` + - `"text"` - - `"code_interpreter"` + - `ResponseFormatJSONObject object { type }` - - `FileSearchTool object { type }` + 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: "file_search"` + - `type: "json_object"` - The type of tool being defined: `file_search` + The type of response format being defined. Always `json_object`. - - `"file_search"` + - `"json_object"` - - `completed_at: number` + - `ResponseFormatJSONSchema object { json_schema, type }` - The Unix timestamp (in seconds) for when the message was completed. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + - `json_schema: object { name, description, schema, strict }` - The content of the message in array of text and/or images. + Structured Outputs configuration options, including a JSON Schema. - - `ImageFileContentBlock object { image_file, type }` + - `name: string` - References an image [File](/docs/api-reference/files) in the content of a message. + 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. - - `image_file: ImageFile` + - `description: optional string` - - `file_id: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `schema: optional map[unknown]` - - `detail: optional "auto" or "low" or "high"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `strict: optional boolean` - - `"auto"` + 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). - - `"low"` + - `type: "json_schema"` - - `"high"` + The type of response format being defined. Always `json_schema`. - - `type: "image_file"` + - `"json_schema"` - Always `image_file`. + - `started_at: number` - - `"image_file"` + The Unix timestamp (in seconds) for when the run was started. - - `ImageURLContentBlock object { image_url, type }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - References an image URL in the content of a message. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `image_url: ImageURL` + - `"queued"` - - `url: string` + - `"in_progress"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"requires_action"` - - `detail: optional "auto" or "low" or "high"` + - `"cancelling"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"cancelled"` - - `"auto"` + - `"failed"` - - `"low"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `type: "image_url"` + - `"expired"` - The type of the content part. + - `thread_id: string` - - `"image_url"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `TextContentBlock object { text, type }` + - `tool_choice: AssistantToolChoiceOption` - The text content that is part of a message. + 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. - - `text: Text` + - `"none" or "auto" or "required"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + `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. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"none"` - 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. + - `"auto"` - - `end_index: number` + - `"required"` - - `file_citation: object { file_id }` + - `AssistantToolChoice object { type, function }` - - `file_id: string` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The ID of the specific File the citation is from. + - `type: "function" or "code_interpreter" or "file_search"` - - `start_index: number` + The type of the tool. If type is `function`, the function name must be set - - `text: string` + - `"function"` - The text in the message content that needs to be replaced. + - `"code_interpreter"` - - `type: "file_citation"` + - `"file_search"` - Always `file_citation`. + - `function: optional AssistantToolChoiceFunction` - - `"file_citation"` + - `name: string` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The name of the function to call. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `end_index: number` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `file_path: object { file_id }` + - `CodeInterpreterTool object { type }` - - `file_id: string` + - `type: "code_interpreter"` - The ID of the file that was generated. + The type of tool being defined: `code_interpreter` - - `start_index: number` + - `"code_interpreter"` - - `text: string` + - `FileSearchTool object { type, file_search }` - The text in the message content that needs to be replaced. + - `type: "file_search"` - - `type: "file_path"` + The type of tool being defined: `file_search` - Always `file_path`. + - `"file_search"` - - `"file_path"` + - `file_search: optional object { max_num_results, ranking_options }` - - `value: string` + Overrides for the file search tool. - The data that makes up the text. + - `max_num_results: optional number` - - `type: "text"` + 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. - Always `text`. + 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. - - `"text"` + - `ranking_options: optional object { score_threshold, ranker }` - - `RefusalContentBlock object { refusal, type }` + 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. - The refusal content generated by the assistant. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `refusal: string` + - `score_threshold: number` - - `type: "refusal"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Always `refusal`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"refusal"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `created_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the message was created. + - `"default_2024_08_21"` - - `incomplete_at: number` + - `FunctionTool object { function, type }` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `function: FunctionDefinition` - - `incomplete_details: object { reason }` + - `name: string` - On an incomplete message, details about why the message is incomplete. + 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. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `description: optional string` - The reason the message is incomplete. + A description of what the function does, used by the model to choose when and how to call the function. - - `"content_filter"` + - `parameters: optional FunctionParameters` - - `"max_tokens"` + 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. - - `"run_cancelled"` + Omitting `parameters` defines a function with an empty parameter list. - - `"run_expired"` + - `strict: optional boolean` - - `"run_failed"` + 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` + - `type: "function"` - 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. + The type of tool being defined: `function` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"function"` - - `object: "thread.message"` + - `truncation_strategy: object { type, last_messages }` - The object type, which is always `thread.message`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"thread.message"` + - `type: "auto" or "last_messages"` - - `role: "user" or "assistant"` + 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`. - The entity that produced the message. One of `user` or `assistant`. + - `"auto"` - - `"user"` + - `"last_messages"` - - `"assistant"` + - `last_messages: optional number` - - `run_id: string` + The number of most recent messages from the thread when constructing the context for the run. - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `status: "in_progress" or "incomplete" or "completed"` + 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.). - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `completion_tokens: number` - - `"in_progress"` + Number of completion tokens used over the course of the run. - - `"incomplete"` + - `prompt_tokens: number` - - `"completed"` + Number of prompt tokens used over the course of the run. - - `thread_id: string` + - `total_tokens: number` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + Total number of tokens used (prompt + completion). -- `first_id: string` + - `temperature: optional number` -- `has_more: boolean` + The sampling temperature used for this run. If not set, defaults to 1. -- `last_id: string` + - `top_p: optional number` -- `object: string` + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ + -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{}' ``` #### Response ```json { - "data": [ - { "id": "id", "assistant_id": "assistant_id", - "attachments": [ + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ { - "file_id": "file_id", + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", "tools": [ { "type": "code_interpreter" } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" + "truncation_strategy": { + "type": "auto", + "last_messages": 1 }, - "metadata": { - "foo": "string" + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" + "temperature": 0, + "top_p": 0 } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "user_id": "user_abc123" + } + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - }, - { - "id": "msg_abc456", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ { - "type": "text", - "text": { - "value": "Hello, what is AI?", - "annotations": [] - } + "type": "code_interpreter" } ], - "attachments": [], - "metadata": {} + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc456", - "has_more": false + }, + "metadata": { + "user_id": "user_abc123" + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } ``` -## Create message - -**post** `/threads/{thread_id}/messages` - -Create a message. - -### Path Parameters - -- `thread_id: string` - -### Body Parameters - -- `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - The text contents of the message. - - - `TextContent = string` - - The text contents of the message. - - - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). - - - `ImageFileContentBlock object { image_file, type }` - - References an image [File](/docs/api-reference/files) in the content of a message. - - - `image_file: ImageFile` - - - `file_id: string` - - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `detail: optional "auto" or "low" or "high"` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: "image_file"` - - Always `image_file`. - - - `"image_file"` +## Domain Types - - `ImageURLContentBlock object { image_url, type }` +### Required Action Function Tool Call - References an image URL in the content of a message. +- `RequiredActionFunctionToolCall object { id, function, type }` - - `image_url: ImageURL` + Tool call objects - - `url: string` + - `id: string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + 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. - - `detail: optional "auto" or "low" or "high"` + - `function: object { arguments, name }` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The function definition. - - `"auto"` + - `arguments: string` - - `"low"` + The arguments that the model expects you to pass to the function. - - `"high"` + - `name: string` - - `type: "image_url"` + The name of the function. - The type of the content part. + - `type: "function"` - - `"image_url"` + The type of tool call the output is required for. For now, this is always `function`. - - `TextContentBlockParam object { text, type }` + - `"function"` - The text content that is part of a message. +### Run - - `text: string` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - Text content to be sent to the model + Represents an execution run on a [thread](/docs/api-reference/threads). - - `type: "text"` + - `id: string` - Always `text`. + The identifier, which can be referenced in API endpoints. - - `"text"` + - `assistant_id: string` -- `role: "user" or "assistant"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The role of the entity that is creating the message. Allowed values include: + - `cancelled_at: number` - - `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. + The Unix timestamp (in seconds) for when the run was cancelled. - - `"user"` + - `completed_at: number` - - `"assistant"` + The Unix timestamp (in seconds) for when the run was completed. -- `attachments: optional array of object { file_id, tools }` + - `created_at: number` - A list of files attached to the message, and the tools they should be added to. + The Unix timestamp (in seconds) for when the run was created. - - `file_id: optional string` + - `expires_at: number` - The ID of the file to attach to the message. + The Unix timestamp (in seconds) for when the run will expire. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `failed_at: number` - The tools to add this file to. + The Unix timestamp (in seconds) for when the run failed. - - `CodeInterpreterTool object { type }` + - `incomplete_details: object { reason }` - - `type: "code_interpreter"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The type of tool being defined: `code_interpreter` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"code_interpreter"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `FileSearchTool object { type }` + - `"max_completion_tokens"` - - `type: "file_search"` + - `"max_prompt_tokens"` - The type of tool being defined: `file_search` + - `instructions: string` - - `"file_search"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. -- `metadata: optional Metadata` + - `last_error: object { code, message }` - 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. + The last error associated with this run. Will be `null` if there are no errors. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` -### Returns + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. -- `Message object { id, assistant_id, attachments, 11 more }` + - `"server_error"` - Represents a message within a [thread](/docs/api-reference/threads). + - `"rate_limit_exceeded"` - - `id: string` + - `"invalid_prompt"` - The identifier, which can be referenced in API endpoints. + - `message: string` - - `assistant_id: string` + A human-readable description of the error. - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `max_completion_tokens: number` - - `attachments: array of object { file_id, tools }` + The maximum number of completion tokens specified to have been used over the course of the run. - A list of files attached to the message, and the tools they were added to. + - `max_prompt_tokens: number` - - `file_id: optional string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The ID of the file to attach to the message. + - `metadata: Metadata` - - `tools: optional array of CodeInterpreterTool or object { type }` + 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. - The tools to add this file to. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `CodeInterpreterTool object { type }` + - `model: string` - - `type: "code_interpreter"` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The type of tool being defined: `code_interpreter` + - `object: "thread.run"` - - `"code_interpreter"` + The object type, which is always `thread.run`. - - `FileSearchTool object { type }` + - `"thread.run"` - - `type: "file_search"` + - `parallel_tool_calls: boolean` - The type of tool being defined: `file_search` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"file_search"` + - `required_action: object { submit_tool_outputs, type }` - - `completed_at: number` + Details on the action required to continue the run. Will be `null` if no action is required. - The Unix timestamp (in seconds) for when the message was completed. + - `submit_tool_outputs: object { tool_calls }` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + Details on the tool outputs needed for this run to continue. - The content of the message in array of text and/or images. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `ImageFileContentBlock object { image_file, type }` + A list of the relevant tool calls. - References an image [File](/docs/api-reference/files) in the content of a message. + - `id: string` - - `image_file: ImageFile` + 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. - - `file_id: string` + - `function: object { arguments, name }` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The function definition. - - `detail: optional "auto" or "low" or "high"` + - `arguments: string` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The arguments that the model expects you to pass to the function. - - `"auto"` + - `name: string` - - `"low"` + The name of the function. - - `"high"` + - `type: "function"` - - `type: "image_file"` + The type of tool call the output is required for. For now, this is always `function`. - Always `image_file`. + - `"function"` - - `"image_file"` + - `type: "submit_tool_outputs"` - - `ImageURLContentBlock object { image_url, type }` + For now, this is always `submit_tool_outputs`. - References an image URL in the content of a message. + - `"submit_tool_outputs"` - - `image_url: ImageURL` + - `response_format: AssistantResponseFormatOption` - - `url: string` + 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`. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + 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). - - `detail: optional "auto" or "low" or "high"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + **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"` - - `"low"` - - - `"high"` + `auto` is the default value - - `type: "image_url"` + - `"auto"` - The type of the content part. + - `ResponseFormatText object { type }` - - `"image_url"` + Default response format. Used to generate text responses. - - `TextContentBlock object { text, type }` + - `type: "text"` - The text content that is part of a message. + The type of response format being defined. Always `text`. - - `text: Text` + - `"text"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + - `ResponseFormatJSONObject object { type }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + 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. - 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. + - `type: "json_object"` - - `end_index: number` + The type of response format being defined. Always `json_object`. - - `file_citation: object { file_id }` + - `"json_object"` - - `file_id: string` + - `ResponseFormatJSONSchema object { json_schema, type }` - The ID of the specific File the citation is from. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `start_index: number` + - `json_schema: object { name, description, schema, strict }` - - `text: string` + Structured Outputs configuration options, including a JSON Schema. - The text in the message content that needs to be replaced. + - `name: string` - - `type: "file_citation"` + 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. - Always `file_citation`. + - `description: optional string` - - `"file_citation"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `schema: optional map[unknown]` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `end_index: number` + - `strict: optional boolean` - - `file_path: object { file_id }` + 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). - - `file_id: string` + - `type: "json_schema"` - The ID of the file that was generated. + The type of response format being defined. Always `json_schema`. - - `start_index: number` + - `"json_schema"` - - `text: string` + - `started_at: number` - The text in the message content that needs to be replaced. + The Unix timestamp (in seconds) for when the run was started. - - `type: "file_path"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - Always `file_path`. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"file_path"` + - `"queued"` - - `value: string` + - `"in_progress"` - The data that makes up the text. + - `"requires_action"` - - `type: "text"` + - `"cancelling"` - Always `text`. + - `"cancelled"` - - `"text"` + - `"failed"` - - `RefusalContentBlock object { refusal, type }` + - `"completed"` - The refusal content generated by the assistant. + - `"incomplete"` - - `refusal: string` + - `"expired"` - - `type: "refusal"` + - `thread_id: string` - Always `refusal`. + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"refusal"` + - `tool_choice: AssistantToolChoiceOption` - - `created_at: number` + 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. - The Unix timestamp (in seconds) for when the message was created. + - `"none" or "auto" or "required"` - - `incomplete_at: number` + `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. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"none"` - - `incomplete_details: object { reason }` + - `"auto"` - On an incomplete message, details about why the message is incomplete. + - `"required"` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `AssistantToolChoice object { type, function }` - The reason the message is incomplete. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"content_filter"` + - `type: "function" or "code_interpreter" or "file_search"` - - `"max_tokens"` + The type of the tool. If type is `function`, the function name must be set - - `"run_cancelled"` + - `"function"` - - `"run_expired"` + - `"code_interpreter"` - - `"run_failed"` + - `"file_search"` - - `metadata: Metadata` + - `function: optional AssistantToolChoiceFunction` - 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. + - `name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the function to call. - - `object: "thread.message"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The object type, which is always `thread.message`. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `"thread.message"` + - `CodeInterpreterTool object { type }` - - `role: "user" or "assistant"` + - `type: "code_interpreter"` - The entity that produced the message. One of `user` or `assistant`. + The type of tool being defined: `code_interpreter` - - `"user"` + - `"code_interpreter"` - - `"assistant"` + - `FileSearchTool object { type, file_search }` - - `run_id: string` + - `type: "file_search"` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The type of tool being defined: `file_search` - - `status: "in_progress" or "incomplete" or "completed"` + - `"file_search"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `file_search: optional object { max_num_results, ranking_options }` - - `"in_progress"` + Overrides for the file search tool. - - `"incomplete"` + - `max_num_results: optional number` - - `"completed"` + 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. - - `thread_id: string` + 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. - The [thread](/docs/api-reference/threads) ID that this message belongs to. + - `ranking_options: optional object { score_threshold, ranker }` -### Example + 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. -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "content": "string", - "role": "user" - }' -``` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. -#### Response + - `score_threshold: number` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + The score threshold for the file search. All values must be a floating point number between 0 and 1. -### Example + - `ranker: optional "auto" or "default_2024_08_21"` -```http -curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }' -``` + The ranker to use for the file search. If not specified will use the `auto` ranker. -#### Response + - `"auto"` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1713226573, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + - `"default_2024_08_21"` -## Modify message + - `FunctionTool object { function, type }` -**post** `/threads/{thread_id}/messages/{message_id}` + - `function: FunctionDefinition` -Modifies a message. + - `name: string` -### Path Parameters + 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. -- `thread_id: string` + - `description: optional string` -- `message_id: string` + A description of what the function does, used by the model to choose when and how to call the function. -### Body Parameters + - `parameters: optional FunctionParameters` -- `metadata: optional Metadata` + 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. - 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. + Omitting `parameters` defines a function with an empty parameter list. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `strict: optional boolean` -### Returns + 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). -- `Message object { id, assistant_id, attachments, 11 more }` + - `type: "function"` - Represents a message within a [thread](/docs/api-reference/threads). + The type of tool being defined: `function` - - `id: string` + - `"function"` - The identifier, which can be referenced in API endpoints. + - `truncation_strategy: object { type, last_messages }` - - `assistant_id: string` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `type: "auto" or "last_messages"` - - `attachments: array of object { file_id, tools }` + 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`. - A list of files attached to the message, and the tools they were added to. + - `"auto"` - - `file_id: optional string` + - `"last_messages"` - The ID of the file to attach to the message. + - `last_messages: optional number` - - `tools: optional array of CodeInterpreterTool or object { type }` + The number of most recent messages from the thread when constructing the context for the run. - The tools to add this file to. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `CodeInterpreterTool object { type }` + 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: "code_interpreter"` + - `completion_tokens: number` - The type of tool being defined: `code_interpreter` + Number of completion tokens used over the course of the run. - - `"code_interpreter"` + - `prompt_tokens: number` - - `FileSearchTool object { type }` + Number of prompt tokens used over the course of the run. - - `type: "file_search"` + - `total_tokens: number` - The type of tool being defined: `file_search` + Total number of tokens used (prompt + completion). - - `"file_search"` + - `temperature: optional number` - - `completed_at: number` + The sampling temperature used for this run. If not set, defaults to 1. - The Unix timestamp (in seconds) for when the message was completed. + - `top_p: optional number` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + The nucleus sampling value used for this run. If not set, defaults to 1. - The content of the message in array of text and/or images. +# Steps - - `ImageFileContentBlock object { image_file, type }` +## List run steps - References an image [File](/docs/api-reference/files) in the content of a message. +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `image_file: ImageFile` +Returns a list of run steps belonging to a run. - - `file_id: string` +### Path Parameters - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. +- `thread_id: string` - - `detail: optional "auto" or "low" or "high"` +- `run_id: string` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. +### Query Parameters - - `"auto"` +- `after: optional string` - - `"low"` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `"high"` +- `before: optional string` - - `type: "image_file"` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - Always `image_file`. +- `include: optional array of RunStepInclude` - - `"image_file"` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - `ImageURLContentBlock object { image_url, type }` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - References an image URL in the content of a message. + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `image_url: ImageURL` +- `limit: optional number` - - `url: string` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. +- `order: optional "asc" or "desc"` - - `detail: optional "auto" or "low" or "high"` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"asc"` - - `"auto"` + - `"desc"` - - `"low"` +### Returns - - `"high"` +- `data: array of RunStep` - - `type: "image_url"` + - `id: string` - The type of the content part. + The identifier of the run step, which can be referenced in API endpoints. - - `"image_url"` + - `assistant_id: string` - - `TextContentBlock object { text, type }` + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - The text content that is part of a message. + - `cancelled_at: number` - - `text: Text` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + - `completed_at: number` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + The Unix timestamp (in seconds) for when the run step completed. - 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. + - `created_at: number` - - `end_index: number` + The Unix timestamp (in seconds) for when the run step was created. - - `file_citation: object { file_id }` + - `expired_at: number` - - `file_id: string` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The ID of the specific File the citation is from. + - `failed_at: number` - - `start_index: number` + The Unix timestamp (in seconds) for when the run step failed. - - `text: string` + - `last_error: object { code, message }` - The text in the message content that needs to be replaced. + The last error associated with this run step. Will be `null` if there are no errors. - - `type: "file_citation"` + - `code: "server_error" or "rate_limit_exceeded"` - Always `file_citation`. + One of `server_error` or `rate_limit_exceeded`. - - `"file_citation"` + - `"server_error"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `"rate_limit_exceeded"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `message: string` - - `end_index: number` + A human-readable description of the error. - - `file_path: object { file_id }` + - `metadata: Metadata` - - `file_id: string` + 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. - The ID of the file that was generated. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `start_index: number` + - `object: "thread.run.step"` - - `text: string` + The object type, which is always `thread.run.step`. - The text in the message content that needs to be replaced. + - `"thread.run.step"` - - `type: "file_path"` + - `run_id: string` - Always `file_path`. + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `"file_path"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `value: string` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The data that makes up the text. + - `"in_progress"` - - `type: "text"` + - `"cancelled"` - Always `text`. + - `"failed"` - - `"text"` + - `"completed"` - - `RefusalContentBlock object { refusal, type }` + - `"expired"` - The refusal content generated by the assistant. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `refusal: string` + The details of the run step. - - `type: "refusal"` + - `MessageCreationStepDetails object { message_creation, type }` - Always `refusal`. + Details of the message creation by the run step. - - `"refusal"` + - `message_creation: object { message_id }` - - `created_at: number` + - `message_id: string` - The Unix timestamp (in seconds) for when the message was created. + The ID of the message that was created by this run step. - - `incomplete_at: number` + - `type: "message_creation"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Always `message_creation`. - - `incomplete_details: object { reason }` + - `"message_creation"` - On an incomplete message, details about why the message is incomplete. + - `ToolCallsStepDetails object { tool_calls, type }` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + Details of the tool call. - The reason the message is incomplete. + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `"content_filter"` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `"max_tokens"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `"run_cancelled"` + Details of the Code Interpreter tool call the run step was involved in. - - `"run_expired"` + - `id: string` - - `"run_failed"` + The ID of the tool call. - - `metadata: Metadata` + - `code_interpreter: object { input, outputs }` - 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. + The Code Interpreter tool call definition. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `input: string` - - `object: "thread.message"` + The input to the Code Interpreter tool call. - The object type, which is always `thread.message`. + - `outputs: array of object { logs, type } or object { image, type }` - - `"thread.message"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `role: "user" or "assistant"` + - `CodeInterpreterLogOutput object { logs, type }` - The entity that produced the message. One of `user` or `assistant`. + Text output from the Code Interpreter tool call as part of a run step. - - `"user"` + - `logs: string` - - `"assistant"` + The text output from the Code Interpreter tool call. - - `run_id: string` + - `type: "logs"` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + Always `logs`. - - `status: "in_progress" or "incomplete" or "completed"` + - `"logs"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `CodeInterpreterImageOutput object { image, type }` - - `"in_progress"` + - `image: object { file_id }` - - `"incomplete"` + - `file_id: string` - - `"completed"` + The [file](/docs/api-reference/files) ID of the image. - - `thread_id: string` + - `type: "image"` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + Always `image`. -### Example + - `"image"` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{}' -``` + - `type: "code_interpreter"` -#### Response + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `"code_interpreter"` -### Example + - `FileSearchToolCall object { id, file_search, type }` -```http -curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' -``` + - `id: string` -#### Response + The ID of the tool call object. -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" - } -} -``` + - `file_search: object { ranking_options, results }` -## Retrieve message + For now, this is always going to be an empty object. -**get** `/threads/{thread_id}/messages/{message_id}` + - `ranking_options: optional object { ranker, score_threshold }` -Retrieve a message. + The ranking options for the file search. -### Path Parameters + - `ranker: "auto" or "default_2024_08_21"` -- `thread_id: string` + The ranker to use for the file search. If not specified will use the `auto` ranker. -- `message_id: string` + - `"auto"` -### Returns + - `"default_2024_08_21"` -- `Message object { id, assistant_id, attachments, 11 more }` + - `score_threshold: number` - Represents a message within a [thread](/docs/api-reference/threads). + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `id: string` + - `results: optional array of object { file_id, file_name, score, content }` - The identifier, which can be referenced in API endpoints. + The results of the file search. - - `assistant_id: string` + - `file_id: string` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + The ID of the file that result was found in. - - `attachments: array of object { file_id, tools }` + - `file_name: string` - A list of files attached to the message, and the tools they were added to. + The name of the file that result was found in. - - `file_id: optional string` + - `score: number` - The ID of the file to attach to the message. + The score of the result. All values must be a floating point number between 0 and 1. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `content: optional array of object { text, type }` - The tools to add this file to. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `CodeInterpreterTool object { type }` + - `text: optional string` - - `type: "code_interpreter"` + The text content of the file. - The type of tool being defined: `code_interpreter` + - `type: optional "text"` - - `"code_interpreter"` + The type of the content. - - `FileSearchTool object { type }` + - `"text"` - `type: "file_search"` - The type of tool being defined: `file_search` + The type of tool call. This is always going to be `file_search` for this type of tool call. - `"file_search"` - - `completed_at: number` - - The Unix timestamp (in seconds) for when the message was completed. - - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - The content of the message in array of text and/or images. + - `FunctionToolCall object { id, function, type }` - - `ImageFileContentBlock object { image_file, type }` + - `id: string` - References an image [File](/docs/api-reference/files) in the content of a message. + The ID of the tool call object. - - `image_file: ImageFile` + - `function: object { arguments, name, output }` - - `file_id: string` + The definition of the function that was called. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `arguments: string` - - `detail: optional "auto" or "low" or "high"` + The arguments passed to the function. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `name: string` - - `"auto"` + The name of the function. - - `"low"` + - `output: string` - - `"high"` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `type: "image_file"` + - `type: "function"` - Always `image_file`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `"image_file"` + - `"function"` - - `ImageURLContentBlock object { image_url, type }` + - `type: "tool_calls"` - References an image URL in the content of a message. + Always `tool_calls`. - - `image_url: ImageURL` + - `"tool_calls"` - - `url: string` + - `thread_id: string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `detail: optional "auto" or "low" or "high"` + - `type: "message_creation" or "tool_calls"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"auto"` + - `"message_creation"` - - `"low"` + - `"tool_calls"` - - `"high"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "image_url"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - The type of the content part. + - `completion_tokens: number` - - `"image_url"` + Number of completion tokens used over the course of the run step. - - `TextContentBlock object { text, type }` + - `prompt_tokens: number` - The text content that is part of a message. + Number of prompt tokens used over the course of the run step. - - `text: Text` + - `total_tokens: number` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + Total number of tokens used (prompt + completion). - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` +- `first_id: string` - 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. +- `has_more: boolean` - - `end_index: number` +- `last_id: string` - - `file_citation: object { file_id }` +- `object: string` - - `file_id: string` +### Example - The ID of the specific File the citation is from. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `start_index: number` +#### Response - - `text: string` +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" +} +``` - The text in the message content that needs to be replaced. +### Example - - `type: "file_citation"` +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" +``` - Always `file_citation`. +#### Response - - `"file_citation"` +```json +{ + "object": "list", + "data": [ + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false +} +``` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` +## Retrieve run step - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - - `end_index: number` +Retrieves a run step. - - `file_path: object { file_id }` +### Path Parameters - - `file_id: string` +- `thread_id: string` - The ID of the file that was generated. +- `run_id: string` - - `start_index: number` +- `step_id: string` - - `text: string` +### Query Parameters - The text in the message content that needs to be replaced. +- `include: optional array of RunStepInclude` - - `type: "file_path"` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - Always `file_path`. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"file_path"` + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `value: string` +### Returns - The data that makes up the text. +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - - `type: "text"` + Represents a step in execution of a run. - Always `text`. + - `id: string` - - `"text"` + The identifier of the run step, which can be referenced in API endpoints. - - `RefusalContentBlock object { refusal, type }` + - `assistant_id: string` - The refusal content generated by the assistant. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `refusal: string` + - `cancelled_at: number` - - `type: "refusal"` + The Unix timestamp (in seconds) for when the run step was cancelled. - Always `refusal`. + - `completed_at: number` - - `"refusal"` + The Unix timestamp (in seconds) for when the run step completed. - `created_at: number` - The Unix timestamp (in seconds) for when the message was created. + The Unix timestamp (in seconds) for when the run step was created. - - `incomplete_at: number` + - `expired_at: number` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + + - `failed_at: number` - - `incomplete_details: object { reason }` + The Unix timestamp (in seconds) for when the run step failed. - On an incomplete message, details about why the message is incomplete. + - `last_error: object { code, message }` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The last error associated with this run step. Will be `null` if there are no errors. - The reason the message is incomplete. + - `code: "server_error" or "rate_limit_exceeded"` - - `"content_filter"` + One of `server_error` or `rate_limit_exceeded`. - - `"max_tokens"` + - `"server_error"` - - `"run_cancelled"` + - `"rate_limit_exceeded"` - - `"run_expired"` + - `message: string` - - `"run_failed"` + A human-readable description of the error. - `metadata: Metadata` @@ -10119,699 +10132,704 @@ Retrieve a message. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: "thread.message"` + - `object: "thread.run.step"` - The object type, which is always `thread.message`. + The object type, which is always `thread.run.step`. - - `"thread.message"` + - `"thread.run.step"` - - `role: "user" or "assistant"` + - `run_id: string` - The entity that produced the message. One of `user` or `assistant`. + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `"user"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"assistant"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `run_id: string` + - `"in_progress"` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `"cancelled"` - - `status: "in_progress" or "incomplete" or "completed"` + - `"failed"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"completed"` - - `"in_progress"` + - `"expired"` - - `"incomplete"` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"completed"` + The details of the run step. - - `thread_id: string` + - `MessageCreationStepDetails object { message_creation, type }` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + Details of the message creation by the run step. -### Example + - `message_creation: object { message_id }` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `message_id: string` -#### Response + The ID of the message that was created by this run step. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `type: "message_creation"` -### Example + Always `message_creation`. -```http -curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `"message_creation"` -#### Response + - `ToolCallsStepDetails object { tool_calls, type }` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + Details of the tool call. -## Delete message + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` -**delete** `/threads/{thread_id}/messages/{message_id}` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. -Deletes a message. + - `CodeInterpreterToolCall object { id, code_interpreter, type }` -### Path Parameters + Details of the Code Interpreter tool call the run step was involved in. -- `thread_id: string` + - `id: string` -- `message_id: string` + The ID of the tool call. -### Returns + - `code_interpreter: object { input, outputs }` -- `MessageDeleted object { id, deleted, object }` + The Code Interpreter tool call definition. - - `id: string` + - `input: string` - - `deleted: boolean` + The input to the Code Interpreter tool call. - - `object: "thread.message.deleted"` + - `outputs: array of object { logs, type } or object { image, type }` - - `"thread.message.deleted"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. -### Example + - `CodeInterpreterLogOutput object { logs, type }` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Text output from the Code Interpreter tool call as part of a run step. -#### Response + - `logs: string` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + The text output from the Code Interpreter tool call. -### Example + - `type: "logs"` -```http -curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + Always `logs`. -#### Response + - `"logs"` -```json -{ - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true -} -``` + - `CodeInterpreterImageOutput object { image, type }` -## Domain Types + - `image: object { file_id }` -### File Citation Annotation + - `file_id: string` -- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + The [file](/docs/api-reference/files) ID of the image. - 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. + - `type: "image"` - - `end_index: number` + Always `image`. - - `file_citation: object { file_id }` + - `"image"` - - `file_id: string` + - `type: "code_interpreter"` - The ID of the specific File the citation is from. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `start_index: number` + - `"code_interpreter"` - - `text: string` + - `FileSearchToolCall object { id, file_search, type }` - The text in the message content that needs to be replaced. + - `id: string` - - `type: "file_citation"` + The ID of the tool call object. - Always `file_citation`. + - `file_search: object { ranking_options, results }` - - `"file_citation"` + For now, this is always going to be an empty object. -### File Citation Delta Annotation + - `ranking_options: optional object { ranker, score_threshold }` -- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The ranking options for the file search. - 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. + - `ranker: "auto" or "default_2024_08_21"` - - `index: number` + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: optional array of object { file_id, file_name, score, content }` + + The results of the file search. + + - `file_id: string` + + The ID of the file that result was found in. + + - `file_name: string` + + The name of the file that result was found in. + + - `score: number` + + The score of the result. All values must be a floating point number between 0 and 1. - The index of the annotation in the text content part. + - `content: optional array of object { text, type }` - - `type: "file_citation"` + The content of the result that was found. The content is only included if requested via the include query parameter. - Always `file_citation`. + - `text: optional string` - - `"file_citation"` + The text content of the file. - - `end_index: optional number` + - `type: optional "text"` - - `file_citation: optional object { file_id, quote }` + The type of the content. - - `file_id: optional string` + - `"text"` - The ID of the specific File the citation is from. + - `type: "file_search"` - - `quote: optional string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The specific quote in the file. + - `"file_search"` - - `start_index: optional number` + - `FunctionToolCall object { id, function, type }` - - `text: optional string` + - `id: string` - The text in the message content that needs to be replaced. + The ID of the tool call object. -### File Path Annotation + - `function: object { arguments, name, output }` -- `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The definition of the function that was called. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `arguments: string` - - `end_index: number` + The arguments passed to the function. - - `file_path: object { file_id }` + - `name: string` - - `file_id: string` + The name of the function. - The ID of the file that was generated. + - `output: string` - - `start_index: number` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `text: string` + - `type: "function"` - The text in the message content that needs to be replaced. + The type of tool call. This is always going to be `function` for this type of tool call. - - `type: "file_path"` + - `"function"` - Always `file_path`. + - `type: "tool_calls"` - - `"file_path"` + Always `tool_calls`. -### File Path Delta Annotation + - `"tool_calls"` -- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `thread_id: string` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `index: number` + - `type: "message_creation" or "tool_calls"` - The index of the annotation in the text content part. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `type: "file_path"` + - `"message_creation"` - Always `file_path`. + - `"tool_calls"` - - `"file_path"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `end_index: optional number` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `file_path: optional object { file_id }` + - `completion_tokens: number` - - `file_id: optional string` + Number of completion tokens used over the course of the run step. - The ID of the file that was generated. + - `prompt_tokens: number` - - `start_index: optional number` + Number of prompt tokens used over the course of the run step. - - `text: optional string` + - `total_tokens: number` - The text in the message content that needs to be replaced. + Total number of tokens used (prompt + completion). -### Image File +### Example -- `ImageFile object { file_id, detail }` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps/$STEP_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `file_id: string` +#### Response - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` - - `detail: optional "auto" or "low" or "high"` +### Example - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"auto"` +#### Response - - `"low"` +```json +{ + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } +} +``` - - `"high"` +## Domain Types -### Image File Content Block +### Code Interpreter Logs -- `ImageFileContentBlock object { image_file, type }` +- `CodeInterpreterLogs object { index, type, logs }` - References an image [File](/docs/api-reference/files) in the content of a message. + Text output from the Code Interpreter tool call as part of a run step. - - `image_file: ImageFile` + - `index: number` - - `file_id: string` + The index of the output in the outputs array. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `type: "logs"` - - `detail: optional "auto" or "low" or "high"` + Always `logs`. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"logs"` - - `"auto"` + - `logs: optional string` - - `"low"` + The text output from the Code Interpreter tool call. - - `"high"` +### Code Interpreter Output Image - - `type: "image_file"` +- `CodeInterpreterOutputImage object { index, type, image }` - Always `image_file`. + - `index: number` - - `"image_file"` + The index of the output in the outputs array. -### Image File Delta + - `type: "image"` -- `ImageFileDelta object { detail, file_id }` + Always `image`. - - `detail: optional "auto" or "low" or "high"` + - `"image"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `image: optional object { file_id }` - - `"auto"` + - `file_id: optional string` - - `"low"` + The [file](/docs/api-reference/files) ID of the image. - - `"high"` +### Code Interpreter Tool Call - - `file_id: optional string` +- `CodeInterpreterToolCall object { id, code_interpreter, type }` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + Details of the Code Interpreter tool call the run step was involved in. -### Image File Delta Block + - `id: string` -- `ImageFileDeltaBlock object { index, type, image_file }` + The ID of the tool call. - References an image [File](/docs/api-reference/files) in the content of a message. + - `code_interpreter: object { input, outputs }` - - `index: number` + The Code Interpreter tool call definition. - The index of the content part in the message. + - `input: string` - - `type: "image_file"` + The input to the Code Interpreter tool call. - Always `image_file`. + - `outputs: array of object { logs, type } or object { image, type }` - - `"image_file"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `image_file: optional ImageFileDelta` + - `CodeInterpreterLogOutput object { logs, type }` - - `detail: optional "auto" or "low" or "high"` + Text output from the Code Interpreter tool call as part of a run step. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `logs: string` - - `"auto"` + The text output from the Code Interpreter tool call. - - `"low"` + - `type: "logs"` - - `"high"` + Always `logs`. - - `file_id: optional string` + - `"logs"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `CodeInterpreterImageOutput object { image, type }` -### Image URL + - `image: object { file_id }` -- `ImageURL object { url, detail }` + - `file_id: string` - - `url: string` + The [file](/docs/api-reference/files) ID of the image. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "image"` - - `detail: optional "auto" or "low" or "high"` + Always `image`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"image"` - - `"auto"` + - `type: "code_interpreter"` - - `"low"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"high"` + - `"code_interpreter"` -### Image URL Content Block +### Code Interpreter Tool Call Delta -- `ImageURLContentBlock object { image_url, type }` +- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - References an image URL in the content of a message. + Details of the Code Interpreter tool call the run step was involved in. - - `image_url: ImageURL` + - `index: number` - - `url: string` + The index of the tool call in the tool calls array. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "code_interpreter"` - - `detail: optional "auto" or "low" or "high"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"code_interpreter"` - - `"auto"` + - `id: optional string` - - `"low"` + The ID of the tool call. - - `"high"` + - `code_interpreter: optional object { input, outputs }` - - `type: "image_url"` + The Code Interpreter tool call definition. - The type of the content part. + - `input: optional string` - - `"image_url"` + The input to the Code Interpreter tool call. -### Image URL Delta + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` -- `ImageURLDelta object { detail, url }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `detail: optional "auto" or "low" or "high"` + - `CodeInterpreterLogs object { index, type, logs }` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Text output from the Code Interpreter tool call as part of a run step. - - `"auto"` + - `index: number` - - `"low"` + The index of the output in the outputs array. - - `"high"` + - `type: "logs"` - - `url: optional string` + Always `logs`. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"logs"` -### Image URL Delta Block + - `logs: optional string` -- `ImageURLDeltaBlock object { index, type, image_url }` + The text output from the Code Interpreter tool call. - References an image URL in the content of a message. + - `CodeInterpreterOutputImage object { index, type, image }` - `index: number` - The index of the content part in the message. + The index of the output in the outputs array. - - `type: "image_url"` + - `type: "image"` - Always `image_url`. + Always `image`. - - `"image_url"` + - `"image"` - - `image_url: optional ImageURLDelta` + - `image: optional object { file_id }` - - `detail: optional "auto" or "low" or "high"` + - `file_id: optional string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The [file](/docs/api-reference/files) ID of the image. - - `"auto"` +### File Search Tool Call - - `"low"` +- `FileSearchToolCall object { id, file_search, type }` - - `"high"` + - `id: string` - - `url: optional string` + The ID of the tool call object. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `file_search: object { ranking_options, results }` -### Message + For now, this is always going to be an empty object. -- `Message object { id, assistant_id, attachments, 11 more }` + - `ranking_options: optional object { ranker, score_threshold }` - Represents a message within a [thread](/docs/api-reference/threads). + The ranking options for the file search. - - `id: string` + - `ranker: "auto" or "default_2024_08_21"` - The identifier, which can be referenced in API endpoints. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `assistant_id: string` + - `"auto"` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `"default_2024_08_21"` - - `attachments: array of object { file_id, tools }` + - `score_threshold: number` - A list of files attached to the message, and the tools they were added to. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `file_id: optional string` + - `results: optional array of object { file_id, file_name, score, content }` - The ID of the file to attach to the message. + The results of the file search. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `file_id: string` - The tools to add this file to. + The ID of the file that result was found in. - - `CodeInterpreterTool object { type }` + - `file_name: string` - - `type: "code_interpreter"` + The name of the file that result was found in. - The type of tool being defined: `code_interpreter` + - `score: number` - - `"code_interpreter"` + The score of the result. All values must be a floating point number between 0 and 1. - - `FileSearchTool object { type }` + - `content: optional array of object { text, type }` - - `type: "file_search"` + The content of the result that was found. The content is only included if requested via the include query parameter. - The type of tool being defined: `file_search` + - `text: optional string` - - `"file_search"` + The text content of the file. - - `completed_at: number` + - `type: optional "text"` - The Unix timestamp (in seconds) for when the message was completed. + The type of the content. - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + - `"text"` - The content of the message in array of text and/or images. + - `type: "file_search"` - - `ImageFileContentBlock object { image_file, type }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - References an image [File](/docs/api-reference/files) in the content of a message. + - `"file_search"` - - `image_file: ImageFile` +### File Search Tool Call Delta - - `file_id: string` +- `FileSearchToolCallDelta object { file_search, index, type, id }` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `file_search: unknown` - - `detail: optional "auto" or "low" or "high"` + For now, this is always going to be an empty object. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `index: number` - - `"auto"` + The index of the tool call in the tool calls array. - - `"low"` + - `type: "file_search"` - - `"high"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: "image_file"` + - `"file_search"` - Always `image_file`. + - `id: optional string` - - `"image_file"` + The ID of the tool call object. - - `ImageURLContentBlock object { image_url, type }` +### Function Tool Call - References an image URL in the content of a message. +- `FunctionToolCall object { id, function, type }` - - `image_url: ImageURL` + - `id: string` - - `url: string` + The ID of the tool call object. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `function: object { arguments, name, output }` - - `detail: optional "auto" or "low" or "high"` + The definition of the function that was called. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `arguments: string` - - `"auto"` + The arguments passed to the function. - - `"low"` + - `name: string` - - `"high"` + The name of the function. - - `type: "image_url"` + - `output: string` - The type of the content part. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"image_url"` + - `type: "function"` - - `TextContentBlock object { text, type }` + The type of tool call. This is always going to be `function` for this type of tool call. - The text content that is part of a message. + - `"function"` - - `text: Text` +### Function Tool Call Delta - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` +- `FunctionToolCallDelta object { index, type, id, function }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `index: number` - 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. + The index of the tool call in the tool calls array. - - `end_index: number` + - `type: "function"` - - `file_citation: object { file_id }` + The type of tool call. This is always going to be `function` for this type of tool call. - - `file_id: string` + - `"function"` - The ID of the specific File the citation is from. + - `id: optional string` - - `start_index: number` + The ID of the tool call object. - - `text: string` + - `function: optional object { arguments, name, output }` - The text in the message content that needs to be replaced. + The definition of the function that was called. - - `type: "file_citation"` + - `arguments: optional string` - Always `file_citation`. + The arguments passed to the function. - - `"file_citation"` + - `name: optional string` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The name of the function. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `output: optional string` - - `end_index: number` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `file_path: object { file_id }` +### Message Creation Step Details - - `file_id: string` +- `MessageCreationStepDetails object { message_creation, type }` - The ID of the file that was generated. + Details of the message creation by the run step. - - `start_index: number` + - `message_creation: object { message_id }` - - `text: string` + - `message_id: string` - The text in the message content that needs to be replaced. + The ID of the message that was created by this run step. - - `type: "file_path"` + - `type: "message_creation"` - Always `file_path`. + Always `message_creation`. - - `"file_path"` + - `"message_creation"` - - `value: string` +### Run Step - The data that makes up the text. +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - - `type: "text"` + Represents a step in execution of a run. - Always `text`. + - `id: string` - - `"text"` + The identifier of the run step, which can be referenced in API endpoints. - - `RefusalContentBlock object { refusal, type }` + - `assistant_id: string` - The refusal content generated by the assistant. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `refusal: string` + - `cancelled_at: number` - - `type: "refusal"` + The Unix timestamp (in seconds) for when the run step was cancelled. - Always `refusal`. + - `completed_at: number` - - `"refusal"` + The Unix timestamp (in seconds) for when the run step completed. - `created_at: number` - The Unix timestamp (in seconds) for when the message was created. + The Unix timestamp (in seconds) for when the run step was created. - - `incomplete_at: number` + - `expired_at: number` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `incomplete_details: object { reason }` + - `failed_at: number` - On an incomplete message, details about why the message is incomplete. + The Unix timestamp (in seconds) for when the run step failed. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `last_error: object { code, message }` - The reason the message is incomplete. + The last error associated with this run step. Will be `null` if there are no errors. - - `"content_filter"` + - `code: "server_error" or "rate_limit_exceeded"` - - `"max_tokens"` + One of `server_error` or `rate_limit_exceeded`. - - `"run_cancelled"` + - `"server_error"` - - `"run_expired"` + - `"rate_limit_exceeded"` - - `"run_failed"` + - `message: string` + + A human-readable description of the error. - `metadata: Metadata` @@ -10822,740 +10840,722 @@ curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc1 Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: "thread.message"` - - The object type, which is always `thread.message`. - - - `"thread.message"` - - - `role: "user" or "assistant"` - - The entity that produced the message. One of `user` or `assistant`. + - `object: "thread.run.step"` - - `"user"` + The object type, which is always `thread.run.step`. - - `"assistant"` + - `"thread.run.step"` - `run_id: string` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `status: "in_progress" or "incomplete" or "completed"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - `"in_progress"` - - `"incomplete"` + - `"cancelled"` + + - `"failed"` - `"completed"` - - `thread_id: string` + - `"expired"` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` -### Message Deleted + The details of the run step. -- `MessageDeleted object { id, deleted, object }` + - `MessageCreationStepDetails object { message_creation, type }` - - `id: string` + Details of the message creation by the run step. - - `deleted: boolean` + - `message_creation: object { message_id }` - - `object: "thread.message.deleted"` + - `message_id: string` - - `"thread.message.deleted"` + The ID of the message that was created by this run step. -### Message Delta + - `type: "message_creation"` -- `MessageDelta object { content, role }` + Always `message_creation`. - The delta containing the fields that have changed on the Message. + - `"message_creation"` - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `ToolCallsStepDetails object { tool_calls, type }` - The content of the message in array of text and/or images. + Details of the tool call. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - References an image [File](/docs/api-reference/files) in the content of a message. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `index: number` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - The index of the content part in the message. + Details of the Code Interpreter tool call the run step was involved in. - - `type: "image_file"` + - `id: string` - Always `image_file`. + The ID of the tool call. - - `"image_file"` + - `code_interpreter: object { input, outputs }` - - `image_file: optional ImageFileDelta` + The Code Interpreter tool call definition. - - `detail: optional "auto" or "low" or "high"` + - `input: string` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The input to the Code Interpreter tool call. - - `"auto"` + - `outputs: array of object { logs, type } or object { image, type }` - - `"low"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `"high"` + - `CodeInterpreterLogOutput object { logs, type }` - - `file_id: optional string` + Text output from the Code Interpreter tool call as part of a run step. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `logs: string` - - `TextDeltaBlock object { index, type, text }` + The text output from the Code Interpreter tool call. - The text content that is part of a message. + - `type: "logs"` - - `index: number` + Always `logs`. - The index of the content part in the message. + - `"logs"` - - `type: "text"` + - `CodeInterpreterImageOutput object { image, type }` - Always `text`. + - `image: object { file_id }` - - `"text"` + - `file_id: string` - - `text: optional TextDelta` + The [file](/docs/api-reference/files) ID of the image. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `type: "image"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + Always `image`. - 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. + - `"image"` - - `index: number` + - `type: "code_interpreter"` - The index of the annotation in the text content part. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: "file_citation"` + - `"code_interpreter"` - Always `file_citation`. + - `FileSearchToolCall object { id, file_search, type }` - - `"file_citation"` + - `id: string` - - `end_index: optional number` + The ID of the tool call object. - - `file_citation: optional object { file_id, quote }` + - `file_search: object { ranking_options, results }` - - `file_id: optional string` + For now, this is always going to be an empty object. - The ID of the specific File the citation is from. + - `ranking_options: optional object { ranker, score_threshold }` - - `quote: optional string` + The ranking options for the file search. - The specific quote in the file. + - `ranker: "auto" or "default_2024_08_21"` - - `start_index: optional number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `text: optional string` + - `"auto"` - The text in the message content that needs to be replaced. + - `"default_2024_08_21"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `score_threshold: number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `index: number` + - `results: optional array of object { file_id, file_name, score, content }` - The index of the annotation in the text content part. + The results of the file search. - - `type: "file_path"` + - `file_id: string` - Always `file_path`. + The ID of the file that result was found in. - - `"file_path"` + - `file_name: string` - - `end_index: optional number` + The name of the file that result was found in. - - `file_path: optional object { file_id }` + - `score: number` - - `file_id: optional string` + The score of the result. All values must be a floating point number between 0 and 1. - The ID of the file that was generated. + - `content: optional array of object { text, type }` - - `start_index: optional number` + The content of the result that was found. The content is only included if requested via the include query parameter. - `text: optional string` - The text in the message content that needs to be replaced. - - - `value: optional string` - - The data that makes up the text. - - - `RefusalDeltaBlock object { index, type, refusal }` - - The refusal content that is part of a message. - - - `index: number` - - The index of the refusal part in the message. - - - `type: "refusal"` + The text content of the file. - Always `refusal`. + - `type: optional "text"` - - `"refusal"` + The type of the content. - - `refusal: optional string` + - `"text"` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `type: "file_search"` - References an image URL in the content of a message. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `index: number` + - `"file_search"` - The index of the content part in the message. + - `FunctionToolCall object { id, function, type }` - - `type: "image_url"` + - `id: string` - Always `image_url`. + The ID of the tool call object. - - `"image_url"` + - `function: object { arguments, name, output }` - - `image_url: optional ImageURLDelta` + The definition of the function that was called. - - `detail: optional "auto" or "low" or "high"` + - `arguments: string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The arguments passed to the function. - - `"auto"` + - `name: string` - - `"low"` + The name of the function. - - `"high"` + - `output: string` - - `url: optional string` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "function"` - - `role: optional "user" or "assistant"` + The type of tool call. This is always going to be `function` for this type of tool call. - The entity that produced the message. One of `user` or `assistant`. + - `"function"` - - `"user"` + - `type: "tool_calls"` - - `"assistant"` + Always `tool_calls`. -### Message Delta Event + - `"tool_calls"` -- `MessageDeltaEvent object { id, delta, object }` + - `thread_id: string` - Represents a message delta i.e. any changed fields on a message during streaming. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `id: string` + - `type: "message_creation" or "tool_calls"` - The identifier of the message, which can be referenced in API endpoints. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `delta: MessageDelta` + - `"message_creation"` - The delta containing the fields that have changed on the Message. + - `"tool_calls"` - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The content of the message in array of text and/or images. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `completion_tokens: number` - References an image [File](/docs/api-reference/files) in the content of a message. + Number of completion tokens used over the course of the run step. - - `index: number` + - `prompt_tokens: number` - The index of the content part in the message. + Number of prompt tokens used over the course of the run step. - - `type: "image_file"` + - `total_tokens: number` - Always `image_file`. + Total number of tokens used (prompt + completion). - - `"image_file"` +### Run Step Delta Event - - `image_file: optional ImageFileDelta` +- `RunStepDeltaEvent object { id, delta, object }` - - `detail: optional "auto" or "low" or "high"` + Represents a run step delta i.e. any changed fields on a run step during streaming. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `id: string` - - `"auto"` + The identifier of the run step, which can be referenced in API endpoints. - - `"low"` + - `delta: object { step_details }` - - `"high"` + The delta containing the fields that have changed on the run step. - - `file_id: optional string` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The details of the run step. - - `TextDeltaBlock object { index, type, text }` + - `RunStepDeltaMessageDelta object { type, message_creation }` - The text content that is part of a message. + Details of the message creation by the run step. - - `index: number` + - `type: "message_creation"` - The index of the content part in the message. + Always `message_creation`. - - `type: "text"` + - `"message_creation"` - Always `text`. + - `message_creation: optional object { message_id }` - - `"text"` + - `message_id: optional string` - - `text: optional TextDelta` + The ID of the message that was created by this run step. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `ToolCallDeltaObject object { type, tool_calls }` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + Details of the tool call. - 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. + - `type: "tool_calls"` - - `index: number` + Always `tool_calls`. - The index of the annotation in the text content part. + - `"tool_calls"` - - `type: "file_citation"` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - Always `file_citation`. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `"file_citation"` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - - `end_index: optional number` + Details of the Code Interpreter tool call the run step was involved in. - - `file_citation: optional object { file_id, quote }` + - `index: number` - - `file_id: optional string` + The index of the tool call in the tool calls array. - The ID of the specific File the citation is from. + - `type: "code_interpreter"` - - `quote: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The specific quote in the file. + - `"code_interpreter"` - - `start_index: optional number` + - `id: optional string` - - `text: optional string` + The ID of the tool call. - The text in the message content that needs to be replaced. + - `code_interpreter: optional object { input, outputs }` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + The Code Interpreter tool call definition. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `input: optional string` - - `index: number` + The input to the Code Interpreter tool call. - The index of the annotation in the text content part. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `type: "file_path"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Always `file_path`. + - `CodeInterpreterLogs object { index, type, logs }` - - `"file_path"` + Text output from the Code Interpreter tool call as part of a run step. - - `end_index: optional number` + - `index: number` - - `file_path: optional object { file_id }` + The index of the output in the outputs array. - - `file_id: optional string` + - `type: "logs"` - The ID of the file that was generated. + Always `logs`. - - `start_index: optional number` + - `"logs"` - - `text: optional string` + - `logs: optional string` - The text in the message content that needs to be replaced. + The text output from the Code Interpreter tool call. - - `value: optional string` + - `CodeInterpreterOutputImage object { index, type, image }` - The data that makes up the text. + - `index: number` - - `RefusalDeltaBlock object { index, type, refusal }` + The index of the output in the outputs array. - The refusal content that is part of a message. + - `type: "image"` - - `index: number` + Always `image`. - The index of the refusal part in the message. + - `"image"` - - `type: "refusal"` + - `image: optional object { file_id }` - Always `refusal`. + - `file_id: optional string` - - `"refusal"` + The [file](/docs/api-reference/files) ID of the image. - - `refusal: optional string` + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `file_search: unknown` - References an image URL in the content of a message. + For now, this is always going to be an empty object. - `index: number` - The index of the content part in the message. + The index of the tool call in the tool calls array. - - `type: "image_url"` + - `type: "file_search"` - Always `image_url`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"image_url"` + - `"file_search"` - - `image_url: optional ImageURLDelta` + - `id: optional string` - - `detail: optional "auto" or "low" or "high"` + The ID of the tool call object. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `FunctionToolCallDelta object { index, type, id, function }` - - `"auto"` + - `index: number` - - `"low"` + The index of the tool call in the tool calls array. - - `"high"` + - `type: "function"` - - `url: optional string` + The type of tool call. This is always going to be `function` for this type of tool call. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"function"` - - `role: optional "user" or "assistant"` + - `id: optional string` - The entity that produced the message. One of `user` or `assistant`. + The ID of the tool call object. - - `"user"` + - `function: optional object { arguments, name, output }` - - `"assistant"` + The definition of the function that was called. - - `object: "thread.message.delta"` + - `arguments: optional string` - The object type, which is always `thread.message.delta`. + The arguments passed to the function. - - `"thread.message.delta"` + - `name: optional string` -### Refusal Content Block + The name of the function. -- `RefusalContentBlock object { refusal, type }` + - `output: optional string` - The refusal content generated by the assistant. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `refusal: string` + - `object: "thread.run.step.delta"` - - `type: "refusal"` + The object type, which is always `thread.run.step.delta`. - Always `refusal`. + - `"thread.run.step.delta"` - - `"refusal"` +### Run Step Delta Message Delta -### Refusal Delta Block +- `RunStepDeltaMessageDelta object { type, message_creation }` -- `RefusalDeltaBlock object { index, type, refusal }` + Details of the message creation by the run step. - The refusal content that is part of a message. + - `type: "message_creation"` - - `index: number` + Always `message_creation`. - The index of the refusal part in the message. + - `"message_creation"` - - `type: "refusal"` + - `message_creation: optional object { message_id }` - Always `refusal`. + - `message_id: optional string` - - `"refusal"` + The ID of the message that was created by this run step. - - `refusal: optional string` +### Run Step Include -### Text +- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` -- `Text object { annotations, value }` + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` +### Tool Call Delta Object - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` +- `ToolCallDeltaObject object { type, tool_calls }` - 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. + Details of the tool call. - - `end_index: number` + - `type: "tool_calls"` - - `file_citation: object { file_id }` + Always `tool_calls`. - - `file_id: string` + - `"tool_calls"` - The ID of the specific File the citation is from. + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - - `start_index: number` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `text: string` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - The text in the message content that needs to be replaced. + Details of the Code Interpreter tool call the run step was involved in. - - `type: "file_citation"` + - `index: number` - Always `file_citation`. + The index of the tool call in the tool calls array. - - `"file_citation"` + - `type: "code_interpreter"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `"code_interpreter"` - - `end_index: number` + - `id: optional string` - - `file_path: object { file_id }` + The ID of the tool call. - - `file_id: string` + - `code_interpreter: optional object { input, outputs }` + + The Code Interpreter tool call definition. - The ID of the file that was generated. + - `input: optional string` - - `start_index: number` + The input to the Code Interpreter tool call. - - `text: string` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - The text in the message content that needs to be replaced. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `type: "file_path"` + - `CodeInterpreterLogs object { index, type, logs }` - Always `file_path`. + Text output from the Code Interpreter tool call as part of a run step. - - `"file_path"` + - `index: number` - - `value: string` + The index of the output in the outputs array. - The data that makes up the text. + - `type: "logs"` -### Text Content Block + Always `logs`. -- `TextContentBlock object { text, type }` + - `"logs"` - The text content that is part of a message. + - `logs: optional string` - - `text: Text` + The text output from the Code Interpreter tool call. - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + - `CodeInterpreterOutputImage object { index, type, image }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `index: number` - 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. + The index of the output in the outputs array. - - `end_index: number` + - `type: "image"` - - `file_citation: object { file_id }` + Always `image`. - - `file_id: string` + - `"image"` - The ID of the specific File the citation is from. + - `image: optional object { file_id }` - - `start_index: number` + - `file_id: optional string` - - `text: string` + The [file](/docs/api-reference/files) ID of the image. - The text in the message content that needs to be replaced. + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `type: "file_citation"` + - `file_search: unknown` - Always `file_citation`. + For now, this is always going to be an empty object. - - `"file_citation"` + - `index: number` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The index of the tool call in the tool calls array. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `type: "file_search"` - - `end_index: number` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `file_path: object { file_id }` + - `"file_search"` - - `file_id: string` + - `id: optional string` - The ID of the file that was generated. + The ID of the tool call object. - - `start_index: number` + - `FunctionToolCallDelta object { index, type, id, function }` - - `text: string` + - `index: number` - The text in the message content that needs to be replaced. + The index of the tool call in the tool calls array. - - `type: "file_path"` + - `type: "function"` - Always `file_path`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `"file_path"` + - `"function"` - - `value: string` + - `id: optional string` - The data that makes up the text. + The ID of the tool call object. - - `type: "text"` + - `function: optional object { arguments, name, output }` - Always `text`. + The definition of the function that was called. - - `"text"` + - `arguments: optional string` -### Text Content Block Param + The arguments passed to the function. -- `TextContentBlockParam object { text, type }` + - `name: optional string` - The text content that is part of a message. + The name of the function. - - `text: string` + - `output: optional string` - Text content to be sent to the model + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `type: "text"` +### Tool Calls Step Details - Always `text`. +- `ToolCallsStepDetails object { tool_calls, type }` - - `"text"` + Details of the tool call. -### Text Delta + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` -- `TextDelta object { annotations, value }` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + Details of the Code Interpreter tool call the run step was involved in. - 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. + - `id: string` - - `index: number` + The ID of the tool call. - The index of the annotation in the text content part. + - `code_interpreter: object { input, outputs }` - - `type: "file_citation"` + The Code Interpreter tool call definition. - Always `file_citation`. + - `input: string` - - `"file_citation"` + The input to the Code Interpreter tool call. - - `end_index: optional number` + - `outputs: array of object { logs, type } or object { image, type }` - - `file_citation: optional object { file_id, quote }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `file_id: optional string` + - `CodeInterpreterLogOutput object { logs, type }` - The ID of the specific File the citation is from. + Text output from the Code Interpreter tool call as part of a run step. - - `quote: optional string` + - `logs: string` - The specific quote in the file. + The text output from the Code Interpreter tool call. - - `start_index: optional number` + - `type: "logs"` - - `text: optional string` + Always `logs`. - The text in the message content that needs to be replaced. + - `"logs"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `CodeInterpreterImageOutput object { image, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `image: object { file_id }` - - `index: number` + - `file_id: string` - The index of the annotation in the text content part. + The [file](/docs/api-reference/files) ID of the image. - - `type: "file_path"` + - `type: "image"` - Always `file_path`. + Always `image`. - - `"file_path"` + - `"image"` - - `end_index: optional number` + - `type: "code_interpreter"` - - `file_path: optional object { file_id }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `file_id: optional string` + - `"code_interpreter"` - The ID of the file that was generated. + - `FileSearchToolCall object { id, file_search, type }` - - `start_index: optional number` + - `id: string` - - `text: optional string` + The ID of the tool call object. - The text in the message content that needs to be replaced. + - `file_search: object { ranking_options, results }` - - `value: optional string` + For now, this is always going to be an empty object. - The data that makes up the text. + - `ranking_options: optional object { ranker, score_threshold }` -### Text Delta Block + The ranking options for the file search. -- `TextDeltaBlock object { index, type, text }` + - `ranker: "auto" or "default_2024_08_21"` - The text content that is part of a message. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `index: number` + - `"auto"` - The index of the content part in the message. + - `"default_2024_08_21"` - - `type: "text"` + - `score_threshold: number` - Always `text`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"text"` + - `results: optional array of object { file_id, file_name, score, content }` - - `text: optional TextDelta` + The results of the file search. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `file_id: string` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + The ID of the file that result was found in. - 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. + - `file_name: string` - - `index: number` + The name of the file that result was found in. - The index of the annotation in the text content part. + - `score: number` - - `type: "file_citation"` + The score of the result. All values must be a floating point number between 0 and 1. - Always `file_citation`. + - `content: optional array of object { text, type }` - - `"file_citation"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `end_index: optional number` + - `text: optional string` - - `file_citation: optional object { file_id, quote }` + The text content of the file. - - `file_id: optional string` + - `type: optional "text"` - The ID of the specific File the citation is from. + The type of the content. - - `quote: optional string` + - `"text"` - The specific quote in the file. + - `type: "file_search"` - - `start_index: optional number` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `text: optional string` + - `"file_search"` - The text in the message content that needs to be replaced. + - `FunctionToolCall object { id, function, type }` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `id: string` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The ID of the tool call object. - - `index: number` + - `function: object { arguments, name, output }` - The index of the annotation in the text content part. + The definition of the function that was called. - - `type: "file_path"` + - `arguments: string` - Always `file_path`. + The arguments passed to the function. - - `"file_path"` + - `name: string` - - `end_index: optional number` + The name of the function. - - `file_path: optional object { file_id }` + - `output: string` - - `file_id: optional string` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - The ID of the file that was generated. + - `type: "function"` - - `start_index: optional number` + The type of tool call. This is always going to be `function` for this type of tool call. - - `text: optional string` + - `"function"` - The text in the message content that needs to be replaced. + - `type: "tool_calls"` - - `value: optional string` + Always `tool_calls`. - The data that makes up the text. + - `"tool_calls"`