---
title: "Get agents"
method: GET
path: "/api/fleet/agents"
tags: ["Elastic Agents"]
---

# Get agents

`GET /api/fleet/agents`

**Spaces method and path for this operation:**

<div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/agents</span></div>

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 parameters

- `page` number
- `perPage` number
- `kuery` string
- `showAgentless` boolean
- `showInactive` boolean
- `withMetrics` boolean
- `showUpgradeable` boolean
- `getStatusSummary` boolean
- `sortField` string
- `sortOrder` 'asc' | 'desc'
- `searchAfter` string
- `openPit` boolean
- `pitId` string
- `pitKeepAlive` string

## Response `200`

Successful response

- object
  - `items` object[], required
    - `access_api_key` string
    - `access_api_key_id` string
    - `active` boolean, required
    - `agent` object
      - `id` string, required
      - `type` string
      - `version` string, required
    - `audit_unenrolled_reason` string
    - `capabilities` string[]
    - `components` object[]
      - `id` string, required
      - `message` string, required
      - `status` 'STARTING' | 'CONFIGURING' | 'HEALTHY' | 'DEGRADED' | 'FAILED' | 'STOPPING' | 'STOPPED', required
      - `type` string, required
      - `units` object[]
        - `id` string, required
        - `message` string, required
        - `payload` object
        - `status` 'STARTING' | 'CONFIGURING' | 'HEALTHY' | 'DEGRADED' | 'FAILED' | 'STOPPING' | 'STOPPED', required
        - `type` 'input' | 'output' | '', required
    - `default_api_key` string
    - `default_api_key_history` object[]
      - `id` string, required
      - `retired_at` string, required
    - `default_api_key_id` string
    - `effective_config` unknown, required
    - `enrolled_at` string, required
    - `health` object
    - `id` string, required
    - `identifying_attributes` object
    - `last_checkin` string
    - `last_checkin_message` string
    - `last_checkin_status` 'error' | 'online' | 'degraded' | 'updating' | 'starting' | 'disconnected'
    - `last_known_status` 'offline' | 'error' | 'online' | 'inactive' | 'enrolling' | 'unenrolling' | 'unenrolled' | 'updating' | 'degraded' | 'uninstalled' | 'orphaned'
    - `local_metadata` object, required
    - `metrics` object
      - `cpu_avg` number
      - `memory_size_byte_avg` number
    - `namespaces` string[]
    - `non_identifying_attributes` object
    - `outputs` object
    - `packages` string[], required
    - `pipeline_config` string
    - `policy_base_id` string
    - `policy_id` string
    - `policy_revision` number, nullable
    - `sequence_num` number
    - `signals` string[]
    - `sort` unknown[]
      - unknown
    - `status` 'offline' | 'error' | 'online' | 'inactive' | 'enrolling' | 'unenrolling' | 'unenrolled' | 'updating' | 'degraded' | 'uninstalled' | 'orphaned'
    - `tags` string[]
    - `type` 'PERMANENT' | 'EPHEMERAL' | 'TEMPORARY' | 'OPAMP', required
    - `unenrolled_at` string
    - `unenrollment_started_at` string
    - `unhealthy_reason` string[], nullable
    - `upgrade` object
      - `rollbacks` object[]
        - `valid_until` string, required
        - `version` string, required
    - `upgrade_attempts` string[], nullable
    - `upgrade_details` object, nullable
      - `action_id` string, required
      - `metadata` object
        - `download_percent` number
        - `download_rate` number
        - `error_msg` string
        - `failed_state` '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` 'UPG_REQUESTED' | 'UPG_SCHEDULED' | 'UPG_DOWNLOADING' | 'UPG_EXTRACTING' | 'UPG_REPLACING' | 'UPG_RESTARTING' | 'UPG_FAILED' | 'UPG_WATCHING' | 'UPG_ROLLBACK', required
      - `target_version` string, required
    - `upgrade_started_at` string, nullable
    - `upgraded_at` string, nullable
    - `user_provided_metadata` object
  - `nextSearchAfter` string
  - `page` number, required
  - `perPage` number, required
  - `pit` string
  - `statusSummary` object
  - `total` number, required

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/versions/531c9e2a7d23/schema)