---
title: "List Agents"
method: GET
path: "/v1/convai/agents"
tags: ["Agents Platform"]
---

# List Agents

`GET /v1/convai/agents`

Returns a list of your agents and their metadata.

## Query parameters

- `page_size` integer — How many Agents to return at maximum. Can not exceed 100, defaults to 30.
- `search` string, nullable — Search by agents name.
- `archived` boolean, nullable — Filter agents by archived status
- `show_only_owned_agents` boolean — If set to true, the endpoint will omit any agents that were shared with you by someone else and include only the ones you own. Deprecated: use created_by_user_id instead.
- `created_by_user_id` string, nullable — Filter agents by creator user ID. When set, only agents created by this user are returned. Takes precedence over show_only_owned_agents. Use '@me' to refer to the authenticated user.
- `sort_direction` 'asc' | 'desc'
- `sort_by` 'name' | 'created_at' | 'call_count_7d'
- `cursor` string, nullable — Used for fetching next page. Cursor is returned in the response.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Response `200`

Successful Response

- GetAgentsPageResponseModel
  - `agents` AgentSummaryResponseModel[], required — A list of agents and their metadata
    - `agent_id` string, required — The ID of the agent
    - `name` string, required — The name of the agent
    - `tags` string[], required — Agent tags used to categorize the agent
    - `created_at_unix_secs` integer, required — The creation time of the agent in unix seconds
    - `access_info` ResourceAccessInfo, required
      - `is_creator` boolean, required — Whether the user making the request is the creator of the agent
      - `creator_name` string, required — Name of the agent's creator
      - `creator_email` string, required — Email of the agent's creator
      - `role` 'admin' | 'editor' | 'commenter' | 'viewer', required — The role of the user making the request
      - `anonymous_access_level_override` 'admin' | 'editor' | 'commenter' | 'viewer', nullable — The access level for anonymous users. If None, the resource is not shared publicly.
      - `access_source` 'creator' | 'explicit' | 'workspace_admin' | 'workspace_default', nullable — Why the requesting user has access to this resource. 'creator' = caller is the owner. 'explicit' = caller (or one of their workspace groups) is listed in role_to_group_ids beyond the workspace-wide everyone group. 'workspace_default' = the workspace-wide everyone group is listed in role_to_group_ids (every non-anon workspace member, including admins, sees this resource). 'workspace_admin' = caller is a workspace admin and the admin seat is the *only* path to access; reserved for docs nobody else can see. Lets the UI disclose why an admin-bypass viewer sees a doc that wasn't explicitly shared with them.
    - `last_call_time_unix_secs` integer, nullable — The time of the most recent call in unix seconds, null if no calls have been made
    - `archived` boolean — Whether the agent is archived
  - `next_cursor` string, nullable — The next cursor to paginate through the agents
  - `has_more` boolean, required — Whether there are more agents to paginate through

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/revisions/6c2d6eb4a7e6/schema)