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

2025/08/13 • 2 updated methods

RunSteps_ListRunSteps (updated)
Description :  Gets a list of run steps from a thread run.
Reference :  Link ¶

⚶ Changes

{
  "#id": "RunSteps_ListRunSteps",
  "$responses": {
    "200": {
      "$properties": {
        "data": {
          "$properties": [
            {
              "#name": "type",
              "Enum": {
                "new": [
                  [
                    "message_creation",
                    "Represents a run step to create a message."
                  ],
                  [
                    "tool_calls",
                    "Represents a run step that calls tools."
                  ],
                  [
                    "activities",
                    "Represents a run step with activities information."
                  ]
                ],
                "old": [
                  [
                    "message_creation",
                    "Represents a run step to create a message."
                  ],
                  [
                    "tool_calls",
                    "Represents a run step that calls tools."
                  ]
                ]
              }
            },
            {
              "step_details": [
                {
                  "#name": "type",
                  "Enum": {
                    "new": [
                      [
                        "message_creation",
                        "Represents a run step to create a message."
                      ],
                      [
                        "tool_calls",
                        "Represents a run step that calls tools."
                      ],
                      [
                        "activities",
                        "Represents a run step with activities information."
                      ]
                    ],
                    "old": [
                      [
                        "message_creation",
                        "Represents a run step to create a message."
                      ],
                      [
                        "tool_calls",
                        "Represents a run step that calls tools."
                      ]
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

⚼ Request

GET:  /threads/{threadId}/runs/{runId}/steps
{
threadId:
{
Description: Identifier of the thread. ,
Required: True ,
}
string ,
runId:
{
Description: Identifier of the run. ,
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 ,
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.step'. ,
Enum:
{
thread.run.step: No description available. ,
}
,
Required: True ,
}
enum ,
type:
{
Description: The type of run step, which can be either message_creation or tool_calls. ,
Enum:
{
message_creation: Represents a run step to create a message. ,
tool_calls: Represents a run step that calls tools. ,
activities: Represents a run step with activities information. ,
}
,
Required: True ,
}
enum ,
assistant_id:
{
Description: The ID of the agent associated with the run step. ,
Required: True ,
}
string ,
thread_id:
{
Description: The ID of the thread that was run. ,
Required: True ,
}
string ,
run_id:
{
Description: The ID of the run that this run step is a part of. ,
Required: True ,
}
string ,
status:
{
Description: The status of this run step. ,
Enum:
{
in_progress: Represents a run step still in progress. ,
cancelled: Represents a run step that was cancelled. ,
failed: Represents a run step that failed. ,
completed: Represents a run step that successfully completed. ,
expired: Represents a run step that expired before otherwise finishing. ,
}
,
Required: True ,
}
enum ,
step_details:
{
Description: The details for this run step. ,
Required: True ,
}
{
type:
{
Description: The object type. ,
Enum:
{
message_creation: Represents a run step to create a message. ,
tool_calls: Represents a run step that calls tools. ,
activities: Represents a run step with activities information. ,
}
,
Required: True ,
}
enum ,
}
,
last_error:
{
Description: If applicable, information about the last error encountered by this run step. ,
Required: True ,
}
{
code:
{
Description: The error code for this error. ,
Enum:
{
server_error: Represents a server error. ,
rate_limit_exceeded: Represents an error indicating configured rate limits were exceeded. ,
}
,
Required: True ,
}
enum ,
message:
{
Description: The human-readable text associated with this error. ,
Required: True ,
}
string ,
}
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expired_at:
{
Description: The Unix timestamp, in seconds, representing when this item expired. ,
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 ,
usage:
{
Description: Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. ,
Required: False ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run step. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run step. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
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 ,
}
,
]
,
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 ,
}
,
}
RunSteps_GetRunStep (updated)
Description :  Retrieves a single run step from a thread run.
Reference :  Link ¶

⚶ Changes

{
  "#id": "RunSteps_GetRunStep",
  "$responses": {
    "200": {
      "$properties": [
        {
          "#name": "type",
          "Enum": {
            "new": [
              [
                "message_creation",
                "Represents a run step to create a message."
              ],
              [
                "tool_calls",
                "Represents a run step that calls tools."
              ],
              [
                "activities",
                "Represents a run step with activities information."
              ]
            ],
            "old": [
              [
                "message_creation",
                "Represents a run step to create a message."
              ],
              [
                "tool_calls",
                "Represents a run step that calls tools."
              ]
            ]
          }
        },
        {
          "step_details": [
            {
              "#name": "type",
              "Enum": {
                "new": [
                  [
                    "message_creation",
                    "Represents a run step to create a message."
                  ],
                  [
                    "tool_calls",
                    "Represents a run step that calls tools."
                  ],
                  [
                    "activities",
                    "Represents a run step with activities information."
                  ]
                ],
                "old": [
                  [
                    "message_creation",
                    "Represents a run step to create a message."
                  ],
                  [
                    "tool_calls",
                    "Represents a run step that calls tools."
                  ]
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

⚼ Request

GET:  /threads/{threadId}/runs/{runId}/steps/{stepId}
{
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 ,
stepId:
{
Description: Identifier of the run step. ,
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 ,
}

⚐ 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.step'. ,
Enum:
{
thread.run.step: No description available. ,
}
,
Required: True ,
}
enum ,
type:
{
Description: The type of run step, which can be either message_creation or tool_calls. ,
Enum:
{
message_creation: Represents a run step to create a message. ,
tool_calls: Represents a run step that calls tools. ,
activities: Represents a run step with activities information. ,
}
,
Required: True ,
}
enum ,
assistant_id:
{
Description: The ID of the agent associated with the run step. ,
Required: True ,
}
string ,
thread_id:
{
Description: The ID of the thread that was run. ,
Required: True ,
}
string ,
run_id:
{
Description: The ID of the run that this run step is a part of. ,
Required: True ,
}
string ,
status:
{
Description: The status of this run step. ,
Enum:
{
in_progress: Represents a run step still in progress. ,
cancelled: Represents a run step that was cancelled. ,
failed: Represents a run step that failed. ,
completed: Represents a run step that successfully completed. ,
expired: Represents a run step that expired before otherwise finishing. ,
}
,
Required: True ,
}
enum ,
step_details:
{
Description: The details for this run step. ,
Required: True ,
}
{
type:
{
Description: The object type. ,
Enum:
{
message_creation: Represents a run step to create a message. ,
tool_calls: Represents a run step that calls tools. ,
activities: Represents a run step with activities information. ,
}
,
Required: True ,
}
enum ,
}
,
last_error:
{
Description: If applicable, information about the last error encountered by this run step. ,
Required: True ,
}
{
code:
{
Description: The error code for this error. ,
Enum:
{
server_error: Represents a server error. ,
rate_limit_exceeded: Represents an error indicating configured rate limits were exceeded. ,
}
,
Required: True ,
}
enum ,
message:
{
Description: The human-readable text associated with this error. ,
Required: True ,
}
string ,
}
,
created_at:
{
Description: The Unix timestamp, in seconds, representing when this object was created. ,
Format: unixtime ,
Required: True ,
}
integer ,
expired_at:
{
Description: The Unix timestamp, in seconds, representing when this item expired. ,
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 ,
usage:
{
Description: Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. ,
Required: False ,
}
{
completion_tokens:
{
Description: Number of completion tokens used over the course of the run step. ,
Format: int64 ,
Required: True ,
}
integer ,
prompt_tokens:
{
Description: Number of prompt tokens used over the course of the run step. ,
Format: int64 ,
Required: True ,
}
integer ,
total_tokens:
{
Description: Total number of tokens used (prompt + completion). ,
Format: int64 ,
Required: True ,
}
integer ,
}
,
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 ,
}

⚐ 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 ,
}
,
}