---
title: "Get extant agents"
method: GET
path: "/v1/user_agents"
tags: ["User Agents"]
---

# Get extant agents

`GET /v1/user_agents`

Gets a list of user agents with basic information.

## Query parameters

- `agent_local_user_uuids` string[]
- `agent_state` 'protected' | 'unprotected' | 'bypassed' | 'pending_uninstall' | 'uninstalled' | 'offline'
- `agent_type` object
  - `value` string
  - `operator` string
- `agent_version` object
  - `value` string
  - `operator` string
- `auto_update` boolean
- `block_page_id` integer
- `browser_extension_status` object
  - `value` string
  - `operator` string
- `cybersight_enabled` boolean
- `cybersight_status` object
  - `value` string
  - `operator` string
- `end_at` string
- `msp_id` integer
- `name_search` object
  - `value` string
  - `operator` string
- `network_ids` integer[]
- `new_agent_states` boolean
- `organization_ids` integer[]
- `page` object
  - `number` integer
  - `size` integer
- `policy_id` integer
- `policy_schedule` string
- `release_channels` object
  - `value` string
  - `operator` string
- `scheduled_policy_id` integer
- `search` string
- `sort` string
- `start_at` string
- `state` 'online' | 'offline'
- `status` string
- `tags` string[]
- `traffic_received_last_15_mins` boolean
- `type` 'proxy' | 'agents'
- `vpn_mode` object
  - `value` string
  - `operator` string
- `vpn_status` object
  - `value` string
  - `operator` string

## Response `200`

User agents basic information

- object
  - `data` UserAgentSpec[]
    - `id` string — Resource Id (integer or uuid)
    - `type` string — Resource type name
    - `uuid` string — Resource UUID (if applicable)
    - `attributes` UserAgent — User agent resource
      - `agent_type` 'proxy' | 'windows' | 'macos' | 'linux' | 'android' | 'ios' | 'embedded' | 'dnsmasq' | 'fingbox' — Agent type
      - `agent_version` string — Agent current version
      - `client_id` string — Client generated GUID
      - `hostname` string — Hostname
      - `status` 'active' | 'disabled' | 'uninstalled' | 'uninstalled_from_client' | 'created' — Agent status
      - `os_version` string — Host OS version (may be null)
      - `os_name` string — Host OS name (may be null)
      - `friendly_name` string — Agent friendly name (may be null)
      - `tags` string[] — Agent tags (may be null)
      - `meta` string — Agent meta data (JSON) (may be null)
      - `created_at` string, date — Creation date
      - `updated_at` string, date — Last update
      - `uninstalled_at` string, date — Date when the agent was uninstalled from the machine (may be null)
      - `id_hex` string — Agent UUID in hex representation
      - `id_binary` integer[] — Agent UUID in binary representation
      - `last_sync` string, date — Last sync API received from user agent
      - `agent_state` 'protected' | 'unprotected' | 'bypassed' | 'uninstalled' — Agent state
      - `cyber_sight_client` object — Cyber sight client information
        - `service_state` 'not_installed' | 'operational' | 'disabled' | 'error'
        - `chrome_extension_status` 'not_installed' | 'operational' | 'disabled' | 'error' | 'outdated' | 'install_disabled' | 'browser_not_installed' | 'not_communicating'
        - `edge_extension_status` 'not_installed' | 'operational' | 'disabled' | 'error' | 'outdated' | 'install_disabled' | 'browser_not_installed' | 'not_communicating'
      - `cyber_sight_client_setting` object — Cyber sight client settings
        - `enable_browser_extension` boolean
      - `device_setting` object — Device settings
        - `auto_updates` boolean
        - `enable_cyber_sight` boolean
      - `filtering_client_setting` UserAgentFilteringClientSetting — User agent filtering client setting
        - `auto_updates` boolean — Auto updates setting
        - `connection_method` 'inherit' | 'transparent_prox' | 'loopback' — Configures connection type
        - `filtering_method` 'inherit' | 'precheck' | 'dns_filtering' — Configures filtering mode
        - `fail_over_method` 'inherit' | 'fail_open' | 'fail_close' — Configures fail over method
    - `relationships` object — ] User agent associated objects
      - `network` object
        - `data` IdType — JSON API resource ID and type attributes
          - `id` string — Resource Id (integer or uuid)
          - `type` string — Resource type name
          - `uuid` string — Resource UUID (if applicable)
      - `policy` object
        - `data` IdType — JSON API resource ID and type attributes
          - `id` string — Resource Id (integer or uuid)
          - `type` string — Resource type name
          - `uuid` string — Resource UUID (if applicable)
      - `scheduled_policy` object
        - `data` IdType — JSON API resource ID and type attributes
          - `id` string — Resource Id (integer or uuid)
          - `type` string — Resource type name
          - `uuid` string — Resource UUID (if applicable)
  - `links` Links — JSON API links member representation
    - `self` string — Endpoint URL (may be null)
  - `meta` object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity

---

[API](https://skmtc.net/dnsfilter/apis/dnsfilter-api.md) · [All operations](https://skmtc.net/dnsfilter/apis/dnsfilter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dnsfilter/dnsfilter-api/revisions/29e5e6ee3316/schema)