---
title: "List agent accounts under your ownership scope"
method: GET
path: "/agents"
tags: ["Agents"]
---

# List agent accounts under your ownership scope

`GET /agents`

## Request

- Base URL: `https://api.carbonvoice.app`
- URL: `https://api.carbonvoice.app/agents`
- Auth: one of:
  - API key in header `pxtoken`
  - OAuth 2 (implicit, authorization URL `https://api.carbonvoice.app/oauth/authorize`)

Returns every agent whose `creator_id` equals your root human: your own user id for a human caller, or that same root human for an agent caller (so agent users can list sibling agents under one human account).

## Query parameters

- `skip` number
- `limit` number, nullable
- `direction` 'older' | 'newer', nullable
- `date` string

## Response `200`

- ListAgentAccountsResponse
  - `pagination` ListAgentAccountsPagination, required
    - `skip` number, required
    - `limit` number, required
    - `direction` 'older' | 'newer', nullable
    - `date` string, date-time, nullable
  - `total_results` number, required
  - `results` Agent[], required
    - `id` string, required
    - `name` string, required
    - `username` string, required
    - `creator_id` string, required: Root human user id for this agent (API field). Persisted as `user.owner_id` on the agent user row.
    - `image_url` string, nullable
    - `created_at` string, date-time, required
    - `last_updated_at` string, date-time, required

## Other responses

- `403`

---

[API](https://skmtc.dev/carbonvoice/apis/carbon-voice-api.md) · [All operations](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/revisions/b91c5c845122?raw)