Azure.AI.Agents (preview:2025-05-15)

2025/12/01 • 7 updated methods

Runs_ListRuns (updated)
Description :  Gets a list of runs for a specified thread.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_ListRuns",
  "$responses": {
    "200": {
      "$properties": {
        "data": {
          "$properties": [
            {
              "#name": "status",
              "Enum": {
                "new": [
                  [
                    "queued",
                    "Represents a run that is queued to start."
                  ],
                  [
                    "in_progress",
                    "Represents a run that is in progress."
                  ],
                  [
                    "requires_action",
                    "Represents a run that needs another operation, such as tool output submission, to continue."
                  ],
                  [
                    "cancelling",
                    "Represents a run that is in the process of cancellation."
                  ],
                  [
                    "cancelled",
                    "Represents a run that has been cancelled."
                  ],
                  [
                    "failed",
                    "Represents a run that failed."
                  ],
                  [
                    "completed",
                    "Represents a run that successfully completed."
                  ],
                  [
                    "expired",
                    "Represents a run that expired before it could otherwise finish."
                  ],
                  [
                    "incomplete",
                    "Represents a run that cannot be completed due to safety guardrails."
                  ]
                ],
                "old": [
                  [
                    "queued",
                    "Represents a run that is queued to start."
                  ],
                  [
                    "in_progress",
                    "Represents a run that is in progress."
                  ],
                  [
                    "requires_action",
                    "Represents a run that needs another operation, such as tool output submission, to continue."
                  ],
                  [
                    "cancelling",
                    "Represents a run that is in the process of cancellation."
                  ],
                  [
                    "cancelled",
                    "Represents a run that has been cancelled."
                  ],
                  [
                    "failed",
                    "Represents a run that failed."
                  ],
                  [
                    "completed",
                    "Represents a run that successfully completed."
                  ],
                  [
                    "expired",
                    "Represents a run that expired before it could otherwise finish."
                  ]
                ]
              }
            }
          ]
        }
      }
    }
  }
}

⚼ Request

GET:  /threads/{threadId}/runs
{
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
limit:
{
Description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. ,
Format: int32 ,
Required: False ,
}
integer ,
order:
{
Description: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order. ,
Required: False ,
}
string ,
after:
{
Description: 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. ,
Required: False ,
}
string ,
before:
{
Description: 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, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. ,
Required: False ,
}
string ,
}

⚐ Response (200)

{
data:
{
Description: The requested list of items. ,
Required: True ,
}
[
{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}
,
]
,
last_id:
{
Description: The last ID represented in this list. ,
Required: False ,
}
string ,
has_more:
{
Description: A value indicating whether there are additional values available not captured in this list. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
Runs_CreateRun (updated)
Description :  Creates a new run for an agent thread.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_CreateRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /threads/{threadId}/runs
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
include[]:
{
Description: 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. ,
Required: False ,
}
array ,
body:
{
Required: True ,
}
{
assistant_id:
{
Description: The ID of the agent that should run the thread. ,
Required: True ,
}
string ,
model:
{
Description: The overridden model name that the agent should use to run the thread. ,
Required: False ,
}
string ,
instructions:
{
Description: The overridden system instructions that the agent should use to run the thread. ,
Required: False ,
}
string ,
additional_instructions:
{
Description: Additional instructions to append 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. ,
Required: False ,
}
string ,
additional_messages:
{
Description: Adds additional messages to the thread before creating the run. ,
Required: False ,
}
[
{
role:
{
Description: The role of the entity that is creating the message. Allowed values include: `user`, which indicates the message is sent by an actual user (and should be used in most cases to represent user-generated messages), and `assistant`, which indicates the message is generated by the agent (use this value to insert messages from the agent into the conversation). ,
Enum:
{
user: The role representing the end-user. ,
assistant: The role representing the agent. ,
}
,
Required: True ,
}
enum ,
content:
{
Description: The content of the initial message. This may be a basic string (if you only need text) or an array of typed content blocks (for example, text, image_file, image_url, and so on). ,
Required: True ,
}
string ,
attachments:
{
Description: A list of files attached to the message, and the tools they should be added to. ,
Required: False ,
}
[
{
file_id:
{
Description: The ID of the file to attach to the message. ,
Required: False ,
}
string ,
data_source:
{
Description: Azure asset ID. ,
Required: False ,
}
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
tools:
{
Description: The tools to add to this file. ,
Required: True ,
}
[
string ,
]
,
}
,
]
,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
]
,
tools:
{
Description: The overridden list of enabled tools that the agent should use to run the thread. ,
Required: False ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
tool_resources:
{
Description: The overridden enabled tool resources that the agent should use to run the thread. ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
stream:
{
Description: 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. ,
Required: False ,
}
boolean ,
temperature:
{
Description: 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. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: 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. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: 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. ,
Format: int32 ,
Required: False ,
}
integer ,
max_completion_tokens:
{
Description: 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. ,
Format: int32 ,
Required: False ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: False ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: False ,
}
string ,
response_format:
{
Description: Specifies the format that the model must output. ,
Required: False ,
}
string ,
parallel_tool_calls:
{
Description: If `true` functions will run in parallel during tool use. ,
Required: False ,
}
boolean ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
Runs_GetRun (updated)
Description :  Gets an existing run from an existing thread.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_GetRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

GET:  /threads/{threadId}/runs/{runId}
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
runId:
{
Description: Identifier of the run. ,
Required: True ,
}
string ,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
Runs_UpdateRun (updated)
Description :  Modifies an existing thread run.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_UpdateRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /threads/{threadId}/runs/{runId}
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
runId:
{
Description: Identifier of the run. ,
Required: True ,
}
string ,
body:
{
Required: True ,
}
{
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
Runs_CancelRun (updated)
Description :  Cancels a run of an in‐progress thread.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_CancelRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /threads/{threadId}/runs/{runId}/cancel
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
runId:
{
Description: Identifier of the run. ,
Required: True ,
}
string ,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
Runs_SubmitToolOutputsToRun (updated)
Description :  Submits outputs from tools as requested by tool calls in a run.
Reference :  Link ¶

⚶ Changes

{
  "#id": "Runs_SubmitToolOutputsToRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /threads/{threadId}/runs/{runId}/submit_tool_outputs
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
runId:
{
Description: Identifier of the run. ,
Required: True ,
}
string ,
body:
{
Required: True ,
}
{
tool_outputs:
{
Description: A list of tools for which the outputs are being submitted ,
Required: False ,
}
[
{
type:
{
Description: The object type for the tool output. Defaults to `function_call_output` if not provided. ,
Required: True ,
}
string ,
tool_call_id:
{
Description: The ID of the tool call being resolved, as provided in the tool calls of a required action from a run. ,
Required: False ,
}
string ,
}
,
]
,
tool_approvals:
{
Description: A list of tool approvals allowing data to be sent to tools. ,
Required: False ,
}
[
{
tool_call_id:
{
Description: The ID of the tool call being resolved, as provided in the tool calls of a required action from a run. ,
Required: True ,
}
string ,
approve:
{
Description: The approval boolean value to be submitted. ,
Required: True ,
}
boolean ,
headers:
{
Description: Headers to be attached to the approval. ,
Required: False ,
}
object ,
}
,
]
,
stream:
{
Description: If true, returns a stream of events that happen during the Run as SSE, terminating at `[DONE]`. ,
Required: False ,
}
boolean ,
}
,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}
CreateThreadAndRun (updated)
Description :  Creates a new agent thread and immediately starts a run using that new thread.
Reference :  Link ¶

⚶ Changes

{
  "#id": "CreateThreadAndRun",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "status",
          "Enum": {
            "new": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ],
              [
                "incomplete",
                "Represents a run that cannot be completed due to safety guardrails."
              ]
            ],
            "old": [
              [
                "queued",
                "Represents a run that is queued to start."
              ],
              [
                "in_progress",
                "Represents a run that is in progress."
              ],
              [
                "requires_action",
                "Represents a run that needs another operation, such as tool output submission, to continue."
              ],
              [
                "cancelling",
                "Represents a run that is in the process of cancellation."
              ],
              [
                "cancelled",
                "Represents a run that has been cancelled."
              ],
              [
                "failed",
                "Represents a run that failed."
              ],
              [
                "completed",
                "Represents a run that successfully completed."
              ],
              [
                "expired",
                "Represents a run that expired before it could otherwise finish."
              ]
            ]
          }
        }
      ]
    }
  }
}

⚼ Request

POST:  /threads/runs
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
body:
{
Required: True ,
}
{
assistant_id:
{
Description: The ID of the agent for which the thread should be created. ,
Required: True ,
}
string ,
thread:
{
Description: The details used to create the new thread. If no thread is provided, an empty one will be created. ,
Required: False ,
}
{
messages:
{
Description: The initial messages to associate with the new thread. ,
Required: False ,
}
[
{
role:
{
Description: The role of the entity that is creating the message. Allowed values include: `user`, which indicates the message is sent by an actual user (and should be used in most cases to represent user-generated messages), and `assistant`, which indicates the message is generated by the agent (use this value to insert messages from the agent into the conversation). ,
Enum:
{
user: The role representing the end-user. ,
assistant: The role representing the agent. ,
}
,
Required: True ,
}
enum ,
content:
{
Description: The content of the initial message. This may be a basic string (if you only need text) or an array of typed content blocks (for example, text, image_file, image_url, and so on). ,
Required: True ,
}
string ,
attachments:
{
Description: A list of files attached to the message, and the tools they should be added to. ,
Required: False ,
}
[
{
file_id:
{
Description: The ID of the file to attach to the message. ,
Required: False ,
}
string ,
data_source:
{
Description: Azure asset ID. ,
Required: False ,
}
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
tools:
{
Description: The tools to add to this file. ,
Required: True ,
}
[
string ,
]
,
}
,
]
,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
]
,
tool_resources:
{
Description: A set of resources that are made available to the agent's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
model:
{
Description: The overridden model that the agent should use to run the thread. ,
Required: False ,
}
string ,
instructions:
{
Description: The overridden system instructions the agent should use to run the thread. ,
Required: False ,
}
string ,
tools:
{
Description: The overridden list of enabled tools the agent should use to run the thread. ,
Required: False ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
stream:
{
Description: 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. ,
Required: False ,
}
boolean ,
temperature:
{
Description: 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. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: 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. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: 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. ,
Format: int32 ,
Required: False ,
}
integer ,
max_completion_tokens:
{
Description: 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. ,
Format: int32 ,
Required: False ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: False ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: False ,
}
string ,
response_format:
{
Description: Specifies the format that the model must output. ,
Required: False ,
}
string ,
parallel_tool_calls:
{
Description: If `true` functions will run in parallel during tool use. ,
Required: False ,
}
boolean ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: False ,
}
object ,
}
,
}

⚐ Response (200)

{
id:
{
Description: The identifier, which can be referenced in API endpoints. ,
Required: True ,
}
string ,
object:
{
Description: The object type, which is always 'thread.run'. ,
Enum:
{
thread.run: No description available. ,
}
,
Required: True ,
}
enum ,
thread_id:
{
Description: The ID of the thread associated with this run. ,
Required: True ,
}
string ,
assistant_id:
{
Description: The ID of the agent associated with the thread this run was performed against. ,
Required: True ,
}
string ,
status:
{
Description: The status of the agent thread run. ,
Enum:
{
queued: Represents a run that is queued to start. ,
in_progress: Represents a run that is in progress. ,
requires_action: Represents a run that needs another operation, such as tool output submission, to continue. ,
cancelling: Represents a run that is in the process of cancellation. ,
cancelled: Represents a run that has been cancelled. ,
failed: Represents a run that failed. ,
completed: Represents a run that successfully completed. ,
expired: Represents a run that expired before it could otherwise finish. ,
incomplete: Represents a run that cannot be completed due to safety guardrails. ,
}
,
Required: True ,
}
enum ,
required_action:
{
Description: The details of the action required for the agent thread run to continue. ,
Required: False ,
}
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
last_error:
{
Description: The last error, if any, encountered by this agent thread run. ,
Required: True ,
}
{
code:
{
Description: The status for the error. ,
Required: True ,
}
string ,
message:
{
Description: The human-readable text associated with the error. ,
Required: True ,
}
string ,
}
,
model:
{
Description: The ID of the model to use. ,
Required: True ,
}
string ,
instructions:
{
Description: The overridden system instructions used for this agent thread run. ,
Required: True ,
}
string ,
tools:
{
Description: The overridden enabled tools used for this agent thread run. ,
Required: True ,
}
[
{
type:
{
Description: The object type. ,
Required: True ,
}
string ,
}
,
]
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expires_at:
{
Description: The Unix timestamp, in seconds, representing when this item expires. ,
Format: unixtime ,
Required: True ,
}
integer ,
started_at:
{
Description: The Unix timestamp, in seconds, representing when this item was started. ,
Format: unixtime ,
Required: True ,
}
integer ,
completed_at:
{
Description: The Unix timestamp, in seconds, representing when this completed. ,
Format: unixtime ,
Required: True ,
}
integer ,
cancelled_at:
{
Description: The Unix timestamp, in seconds, representing when this was cancelled. ,
Format: unixtime ,
Required: True ,
}
integer ,
failed_at:
{
Description: The Unix timestamp, in seconds, representing when this failed. ,
Format: unixtime ,
Required: True ,
}
integer ,
incomplete_details:
{
Description: Details on why the run is incomplete. Will be `null` if the run is not incomplete. ,
Required: True ,
}
{
reason:
{
Description: The reason why the run is incomplete. This indicates which specific token limit was reached during the run. ,
Enum:
{
max_completion_tokens: Maximum completion tokens exceeded ,
max_prompt_tokens: Maximum prompt tokens exceeded ,
}
,
Required: True ,
}
enum ,
}
,
usage:
{
Description: 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.). ,
Required: True ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
temperature:
{
Description: The sampling temperature used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
top_p:
{
Description: The nucleus sampling value used for this run. If not set, defaults to 1. ,
Format: float ,
Required: False ,
}
number ,
max_prompt_tokens:
{
Description: The maximum number of prompt tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
max_completion_tokens:
{
Description: The maximum number of completion tokens specified to have been used over the course of the run. ,
Format: int32 ,
Required: True ,
}
integer ,
truncation_strategy:
{
Description: The strategy to use for dropping messages as the context windows moves forward. ,
Required: True ,
}
{
type:
{
Description: The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the `lastMessages` count 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`. ,
Enum:
{
auto: Default value. Messages in the middle of the thread will be dropped to fit the context length of the model. ,
last_messages: The thread will truncate to the `lastMessages` count of recent messages. ,
}
,
Required: True ,
}
enum ,
last_messages:
{
Description: The number of most recent messages from the thread when constructing the context for the run. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
tool_choice:
{
Description: Controls whether or not and which tool is called by the model. ,
Required: True ,
}
string ,
response_format:
{
Description: The response format of the tool calls used in this run. ,
Required: True ,
}
string ,
metadata:
{
Description: A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. ,
Required: True ,
}
object ,
tool_resources:
{
Description: Override the tools the agent can use for this run. This is useful for modifying the behavior on a per-run basis ,
Required: False ,
}
{
code_interpreter:
{
Description: Resources to be used by the `code_interpreter` tool consisting of file IDs. ,
Required: False ,
}
{
file_ids:
{
Description: A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. ,
Required: False ,
}
[
string ,
]
,
data_sources:
{
Description: The data sources to be used. This option is mutually exclusive with the `fileIds` property. ,
Required: False ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
file_search:
{
Description: Resources to be used by the `file_search` tool consisting of vector store IDs. ,
Required: False ,
}
{
vector_store_ids:
{
Description: The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent. ,
Required: False ,
}
[
string ,
]
,
vector_stores:
{
Description: The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool. ,
Required: False ,
}
[
{
name:
{
Description: Name ,
Required: True ,
}
string ,
configuration:
{
Description: Configurations ,
Required: True ,
}
{
data_sources:
{
Description: Data sources ,
Required: True ,
}
[
{
uri:
{
Description: Asset URI. ,
Required: True ,
}
string ,
type:
{
Description: The asset type ,
Enum:
{
uri_asset: Azure URI ,
id_asset: The data ID ,
}
,
Required: True ,
}
enum ,
}
,
]
,
}
,
}
,
]
,
}
,
azure_ai_search:
{
Description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names. ,
Required: False ,
}
{
indexes:
{
Description: The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. ,
Required: False ,
}
[
{
index_connection_id:
{
Description: An index connection id in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
index_name:
{
Description: The name of an index in an IndexResource attached to this agent. ,
Required: False ,
}
string ,
query_type:
{
Description: Type of query in an AIIndexResource attached to this agent. ,
Enum:
{
simple: Query type `simple` ,
semantic: Query type `semantic` ,
vector: Query type `vector` ,
vector_simple_hybrid: Query type `vector_simple_hybrid` ,
vector_semantic_hybrid: Query type `vector_semantic_hybrid` ,
}
,
Required: False ,
}
enum ,
top_k:
{
Description: Number of documents to retrieve from search and present to the model. ,
Format: int32 ,
Required: False ,
}
integer ,
filter:
{
Description: filter string for search resource. ,
Required: False ,
}
string ,
index_asset_id:
{
Description: Index asset id for search resource. ,
Required: False ,
}
string ,
}
,
]
,
}
,
mcp:
{
Description: Resources to be used by the `mcp` tool consisting of a server label and headers. ,
Required: False ,
}
[
{
server_label:
{
Description: The label for the MCP server ,
Required: True ,
}
string ,
headers:
{
Description: The headers for the MCP server updates ,
Required: True ,
}
object ,
require_approval:
{
Description: Does MCP server require approval ,
Required: False ,
}
string ,
}
,
]
,
}
,
parallel_tool_calls:
{
Description: Determines if tools can be executed in parallel within the run. ,
Required: True ,
}
boolean ,
}

⚐ Response (default)

{
error:
{
Description: Represents the error. ,
Required: True ,
}
{
message:
{
Description: Human-readable description of the error. ,
Required: False ,
}
string ,
type:
{
Description: Error type identifier (e.g. `invalid_request_error`). ,
Required: False ,
}
string ,
param:
{
Description: Name of the parameter that caused the error, if applicable. ,
Required: False ,
}
string ,
code:
{
Description: Machine-readable error code. ,
Required: False ,
}
string ,
}
,
}