Skip to main content
Microsoft Foundry
Start building
View as Markdown
View as Markdown
Agents

List agent versions

GET
/agents/{agent_name}/versions

Returns a paged collection of versions for the specified agent.

Path Parameters
agent_namestringrequired
The name of the agent to retrieve versions for.
Query Parameters
limitintegeroptionaldefault: 20
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
orderstringoptional
Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and`desc` for descending order.
ascdesc
afterstringoptional
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.
beforestringoptional
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.
api-versionstringrequired
The API version to use for this operation.
Responses
dataAgentVersionObject[]required
The requested list of items.
metadataobject | nullrequired
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
objectenumrequired
The object type, which is always 'agent.version'.
agent.version
idstringrequired
The unique identifier of the agent version.
namestringrequired
The name of the agent. Name can be used to retrieve/update/delete the agent.
versionstringrequired
The version identifier of the agent. Agents are immutable and every update creates a new version while keeping the name same.
descriptionstring
A human-readable description of the agent.
created_atintegerrequired
The Unix timestamp (seconds) when the agent was created.
definitionhosted | prompt | workflow | externalrequired
statusenum
The provisioning status of the agent version. Defaults to 'active' for non-hosted agents. For hosted agents, reflects infrastructure readiness.
creatingactivefaileddeletingdeleted
instance_identityAgentIdentity
The instance identity of the agent
blueprintAgentIdentity
The blueprint for the agent
blueprint_referenceManagedAgentIdentityBlueprint
The blueprint for the agent
agent_guidstring
The unique GUID identifier of the agent.
first_idstring
The first ID represented in this list.
last_idstring
The last ID represented in this list.
has_morebooleanrequired
A value indicating whether there are additional values available not captured in this list.