GET /api/fleet/agents
Api key auth Basic auth

Spaces method and path for this operation:

get /s/{space_id}/api/fleet/agents

Refer to Spaces for more information.

List agents, with optional filtering and pagination.

[Required authorization] Route required privileges: fleet-agents-read.

Query parameters

  • page number

    Page number

  • perPage number

    Number of results per page

    Default value is 20.

  • kuery string

    A KQL query string to filter results

  • showAgentless boolean

    When true, include agentless agents in the results

    Default value is true.

  • showInactive boolean

    When true, include inactive agents in the results

    Default value is false.

  • withMetrics boolean

    When true, include CPU and memory metrics in the response

    Default value is false.

  • showUpgradeable boolean

    When true, only return agents that are upgradeable

    Default value is false.

  • getStatusSummary boolean

    When true, return a summary of agent statuses in the response

    Default value is false.

  • sortField string

    Field to sort results by

  • sortOrder string

    Sort order, ascending or descending

    Values are asc or 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 application/json

    Successful response

    Hide response attributes Show response attributes object
    • items array[object] Required

      Not more than 10000 elements.

      Hide items attributes Show items attributes object
      • access_api_key string
      • access_api_key_id string
      • active boolean Required
      • agent object

        Additional properties are allowed.

        Hide agent attributes Show agent attributes object
        • id string Required
        • type string
        • version string Required
      • audit_unenrolled_reason string
      • capabilities array[string]

        Not more than 100 elements.

      • components array[object]

        Not more than 10000 elements.

        Hide components attributes Show components attributes object
        • id string Required
        • message string Required
        • status string Required

          Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.

        • type string Required
        • units array[object]

          Not more than 10000 elements.

          Hide units attributes Show units attributes object
          • id string Required
          • message string Required
          • payload object
          • status string Required

            Values are STARTING, CONFIGURING, HEALTHY, DEGRADED, FAILED, STOPPING, or STOPPED.

          • type string Required

            Values are input, output, or .

      • default_api_key string
      • default_api_key_history array[object]

        Not more than 100 elements.

        Hide default_api_key_history attributes Show default_api_key_history attributes object Deprecated
        • id string Required
        • retired_at string Required
      • default_api_key_id string
      • effective_config Required
      • enrolled_at string Required
      • health object
      • id string Required
      • identifying_attributes object
        Hide identifying_attributes attribute Show identifying_attributes attribute object
        • * string Additional properties
      • last_checkin string
      • last_checkin_message string
      • last_checkin_status string

        Values are error, online, degraded, updating, starting, or disconnected.

      • last_known_status string

        Values are offline, error, online, inactive, enrolling, unenrolling, unenrolled, updating, degraded, uninstalled, or orphaned.

      • local_metadata object Required
      • metrics object

        Additional properties are NOT allowed.

        Hide metrics attributes Show metrics attributes object
        • cpu_avg number
        • memory_size_byte_avg number
      • namespaces array[string]

        Not more than 100 elements.

      • non_identifying_attributes object
        Hide non_identifying_attributes attribute Show non_identifying_attributes attribute object
        • * string Additional properties
      • outputs object
        Hide outputs attribute Show outputs attribute object
        • * object Additional properties

          Additional properties are NOT allowed.

          Hide * attributes Show * attributes object
          • api_key_id string
          • to_retire_api_key_ids array[object]

            Not more than 100 elements.

            Hide to_retire_api_key_ids attributes Show to_retire_api_key_ids attributes object
            • id string Required
            • retired_at string Required
          • type string
      • packages array[string] Required

        Not more than 10000 elements.

      • policy_id string
      • policy_revision number | null
      • sequence_num number
      • sort array

        Not more than 10 elements.

      • status string

        Values are offline, error, online, inactive, enrolling, unenrolling, unenrolled, updating, degraded, uninstalled, or orphaned.

      • tags array[string]

        Not more than 100 elements.

      • type string Required

        Values are PERMANENT, EPHEMERAL, TEMPORARY, or OPAMP.

      • unenrolled_at string
      • unenrollment_started_at string
      • unhealthy_reason array[string] | null

        Not more than 3 elements. Values are input, output, or other.

      • upgrade object

        Additional properties are NOT allowed.

        Hide upgrade attribute Show upgrade attribute object
        • rollbacks array[object]

          Not more than 100 elements.

          Hide rollbacks attributes Show rollbacks attributes object
          • valid_until string Required
          • version string Required
      • upgrade_attempts array[string] | null

        Not more than 10000 elements.

      • upgrade_details object | null

        Additional properties are NOT allowed.

        Hide upgrade_details attributes Show upgrade_details attributes object | null
        • action_id string Required
        • metadata object

          Additional properties are NOT allowed.

          Hide metadata attributes Show metadata attributes object
          • download_percent number
          • download_rate number
          • error_msg string
          • failed_state string

            Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.

          • reason string
          • retry_error_msg string
          • retry_until string
          • scheduled_at string
        • state string Required

          Values are UPG_REQUESTED, UPG_SCHEDULED, UPG_DOWNLOADING, UPG_EXTRACTING, UPG_REPLACING, UPG_RESTARTING, UPG_FAILED, UPG_WATCHING, or UPG_ROLLBACK.

        • target_version string Required
      • upgrade_started_at string | null
      • upgraded_at string | null
      • user_provided_metadata object
    • nextSearchAfter string
    • page number Required
    • perPage number Required
    • pit string
    • statusSummary object
      Hide statusSummary attribute Show statusSummary attribute object
      • * number Additional properties
    • total number Required
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • attributes Required
    • error string
    • errorType string
    • message string Required
    • statusCode number
GET /api/fleet/agents 
curl \
 --request GET 'https://localhost:5601/api/fleet/agents' \
 --header "Authorization: $API_KEY"
Response examples (200)
List of agents 
{
  "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
}
Response examples (400)
Example of a generic error response 
{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}