List available agents

Learn more about list available agents.

Use the List available agents to find the agent_id of an active, published agent before you create a schedule or invoke the agent.

HTTP method and endpoint

Use the following HTTP method and endpoint path to list available agents.

GET {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/agents

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`tenant_id`	String	Yes	The unique identifier of your tenant.

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`search`	String	No	Returns only agents whose name or description contains this text. The match is not case-sensitive.	—
`limit`	Integer	No	The maximum number of agents to return per page.	Default: `50`
`page_token`	String	No	The page token from a previous response. Omit to get the first page.	—

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes

Request body

This operation does not require a request body.

Example request

Use the following example to see how a complete request is structured, with headers.

GET {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/agents
Authorization: <access_token>

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`agents`	Array	The agents in this page of results.
`agents[].agent_id`	String	The unique identifier of the agent. Use this when you create a schedule or invoke the agent.
`agents[].name`	String	The display name of the agent.
`agents[].description`	String	The description of what the agent does.
`agents[].tags`	Array	The tags assigned to the agent for categorization.
`agents[].status`	String	The status of the agent: active or archived.
`agents[].version`	Integer	The latest published version number of the agent.
`agents[].updated_at`	String	The date and time when the record was last updated.
`pagination`	Object	Pagination details for fetching the next page of results.
`pagination.total_count`	Integer	The number of items in this page of results.
`pagination.next_page_token`	String	The token to pass as page_token to get the next page of results. Empty when this is the last page.
`pagination.limit`	Integer	The maximum number of items per page.

Example response

The following example shows a successful response.

{
  "agents": [
    {
      "agent_id": "my-support-agent",
      "name": "Customer Support Bot",
      "description": "Handles customer support queries and escalations",
      "tags": [
        "support",
        "customer-facing"
      ],
      "status": "active",
      "version": 3,
      "updated_at": "2025-05-13T10:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 50,
    "next_page_token": "eyJvZmZzZXQiOiA1MH0=",
    "limit": 50
  }
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Unify and manage your data