---
title: "List agents"
method: GET
path: "/api/v2/agents"
tags: ["Agents"]
---

# List agents

`GET /api/v2/agents`

## Request

- Base URL: `https://console.jumpcloud.com`
- URL: `https://console.jumpcloud.com/api/v2/agents`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/docs/api/v2/agents/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves a paginated list of agents in your organization.

## Query parameters

- `pageSize` integer
- `pageToken` string
- `filter` string[]
- `sort` string[]
- `fields` string[]

## Headers

- `x-org-id` string

## Response `200`

Agents retrieved successfully

- AgentList: List of agents.
  - `agents` Agent[], required: Agents matching the request.
    - `id` string, required: Agent ID (24-character hexadecimal string).
    - `organizationId` string, required: Organization ID (24-character hexadecimal string).
    - `name` string, required: Agent name
    - `description` string: Free-text description of this agent
    - `email` string, email, required: Company email address for this agent
    - `ownerId` string, nullable: ID of the human user who owns this agent. Required at creation; becomes null only if the owning user is later deleted.
    - `state` 'active' | 'suspended', required: Lifecycle state (`active` or `suspended`).
  - `totalSize` integer: Total number of agents matching the request after filters are applied.
  - `nextPageToken` string: Opaque cursor for the next page. Omitted when there is no subsequent page.

## Other responses

- `400`: Bad Request
- `401`: Unauthenticated
- `default`: Unexpected error

---

[API](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api.md) - [All operations](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/revisions/f396d9271b46?raw)