---
type: api
title: Get agents
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-fleet-agents
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-fleet-agents
products:
  - Kibana
---

# Get agents

- Server: `https://{kibana_url}`

## Paths

- `GET` `/api/fleet/agents`
- `GET` `/s/{space_id}/api/fleet/agents`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

List agents, with optional filtering and pagination.<br/><br/>[Required authorization] Route required privileges: fleet-agents-read.

## Query String Parameters

- `page` (number)
  Page number
- `perPage` (number · default: 20)
  Number of results per page
- `kuery` (string)
  A KQL query string to filter results
- `showAgentless` (boolean · default: true)
  When true, include agentless agents in the results
- `showInactive` (boolean · default: false)
  When true, include inactive agents in the results
- `withMetrics` (boolean · default: false)
  When true, include CPU and memory metrics in the response
- `showUpgradeable` (boolean · default: false)
  When true, only return agents that are upgradeable
- `getStatusSummary` (boolean · default: false)
  When true, return a summary of agent statuses in the response
- `sortField` (string)
  Field to sort results by
- `sortOrder` (enum)
  Sort order, ascending or descending
  Values: `asc`, `desc`
- `searchAfter` (string)
  JSON-encoded array of sort values for `search_after` pagination
- `openPit` (boolean)
  When true, opens a new point-in-time for pagination
- `pitId` (string)
  Point-in-time ID for pagination
- `pitKeepAlive` (string)
  Duration to keep the point-in-time alive, for example, `1m`

## Responses

#### `200`

Successful response

`application/json`

- `items` ([] object · max: 10000)
  - `access_api_key` (string)
  - `access_api_key_id` (string)
  - `active` (boolean)
  - `agent` (object)
    - `id` (string)
    - `type` (string)
    - `version` (string)
  - `audit_unenrolled_reason` (string)
  - `capabilities` ([] string · max: 100)
  - `components` ([] object · max: 10000)
    - `id` (string)
    - `message` (string)
    - `status` (enum)
      Values: `STARTING`, `CONFIGURING`, `HEALTHY`, `DEGRADED`, `FAILED`, `STOPPING`, `STOPPED`
    - `type` (string)
    - `units` ([] object · max: 10000)
      - `id` (string)
      - `message` (string)
      - `payload` (map string to object)
      - `status` (enum)
        Values: `STARTING`, `CONFIGURING`, `HEALTHY`, `DEGRADED`, `FAILED`, `STOPPING`, `STOPPED`
      - `type` (enum)
        Values: `input`, `output`
  - `default_api_key` (string)
  - `default_api_key_history` ([] object · max: 100)
    - `id` (string)
    - `retired_at` (string)
  - `default_api_key_id` (string)
  - `effective_config` (object)
  - `enrolled_at` (string)
  - `health` (map string to object)
  - `id` (string)
  - `identifying_attributes` (map string to string)
  - `last_checkin` (string)
  - `last_checkin_message` (string)
  - `last_checkin_status` (enum)
    Values: `error`, `online`, `degraded`, `updating`, `starting`, `disconnected`
  - `last_known_status` (enum)
    Values: `offline`, `error`, `online`, `inactive`, `enrolling`, `unenrolling`, `unenrolled`, `updating`, `degraded`, `uninstalled`, `orphaned`
  - `local_metadata` (map string to object)
  - `metrics` (object)
    - `cpu_avg` (number)
    - `memory_size_byte_avg` (number)
  - `namespaces` ([] string · max: 100)
  - `non_identifying_attributes` (map string to string)
  - `outputs` (map string to object)
    Map values (object)
    - `api_key_id` (string)
    - `to_retire_api_key_ids` ([] object · max: 100)
      - `id` (string)
      - `retired_at` (string)
    - `type` (string)
  - `packages` ([] string · max: 10000)
  - `pipeline_config` (string · max: 10000)
  - `policy_base_id` (string)
  - `policy_id` (string)
  - `policy_revision` (number) — nullable
  - `sequence_num` (number)
  - `signals` ([] string · max: 50)
  - `sort` ([] object · max: 10)
  - `status` (enum)
    Values: `offline`, `error`, `online`, `inactive`, `enrolling`, `unenrolling`, `unenrolled`, `updating`, `degraded`, `uninstalled`, `orphaned`
  - `tags` ([] string · max: 100)
  - `type` (enum)
    Values: `PERMANENT`, `EPHEMERAL`, `TEMPORARY`, `OPAMP`
  - `unenrolled_at` (string)
  - `unenrollment_started_at` (string)
  - `unhealthy_reason` ([] enum  · max: 3) — nullable
    Values: `input`, `output`, `other`
  - `upgrade` (object)
    - `rollbacks` ([] object · max: 100)
      - `valid_until` (string)
      - `version` (string)
  - `upgrade_attempts` ([] string · max: 10000) — nullable
  - `upgrade_details` (object) — nullable
    - `action_id` (string)
    - `metadata` (object)
      - `download_percent` (number)
      - `download_rate` (number)
      - `error_msg` (string)
      - `failed_state` (enum)
        Values: `UPG_REQUESTED`, `UPG_SCHEDULED`, `UPG_DOWNLOADING`, `UPG_EXTRACTING`, `UPG_REPLACING`, `UPG_RESTARTING`, `UPG_FAILED`, `UPG_WATCHING`, `UPG_ROLLBACK`
      - `reason` (string)
      - `retry_error_msg` (string)
      - `retry_until` (string)
      - `scheduled_at` (string)
    - `state` (enum)
      Values: `UPG_REQUESTED`, `UPG_SCHEDULED`, `UPG_DOWNLOADING`, `UPG_EXTRACTING`, `UPG_REPLACING`, `UPG_RESTARTING`, `UPG_FAILED`, `UPG_WATCHING`, `UPG_ROLLBACK`
    - `target_version` (string)
  - `upgrade_started_at` (string) — nullable
  - `upgraded_at` (string) — nullable
  - `user_provided_metadata` (map string to object)
- `nextSearchAfter` (string)
- `page` (number)
- `perPage` (number)
- `pit` (string)
- `statusSummary` (map string to number)
- `total` (number)
#### `400`

Bad Request

`application/json`

- `attributes` (object)
- `error` (string)
- `errorType` (string)
- `message` (string)
- `statusCode` (number)
## Code Examples

#### Console

```console
GET /api/fleet/agents
```

#### curl

```curl
curl -X GET "https://{kibana_url}/api/fleet/agents"
```

## Response Examples

#### Get agents

List of agents

```json
{
  "items": [
    {
      "active": true,
      "enrolled_at": "2024-01-01T00:00:00.000Z",
      "id": "agent-id-1",
      "policy_id": "agent-policy-id-1",
      "policy_revision": 1,
      "status": "online",
      "type": "PERMANENT",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "page": 1,
  "perPage": 20,
  "total": 1
}
```

#### Generic error response

Example of a generic error response

```json
{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}
```