---
title: "GET | List all devices"
slug: "api-v2-get-list-all-devices"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-get-list-all-devices"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GET | List all devices

## Description

List the devices associated with your authorization in PAM Core, using the v2 canonical model. Returns a paginated, filterable projection of the `DeviceV2` entity.

              Info

              

This endpoint belongs to the A2A API v2 surface and is available from Segura™ version 4.2.9. Devices are served from the `/api/v2/platform` base path, not from `/api/v2/pam` like other v2 resources. The v1 equivalent is documented in [GET | List all devices](/v4-2/docs/api-get-list-all-devices).

---

## Prerequisites

- Authorization with **read** permission to PAM Core granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).

---

## Request

`GET` `/api/v2/platform/devices`

### Query parameters

All query parameters are optional. When none are provided, the endpoint returns the first page of every device accessible to the authorization, using the list projection defined in the response schema.

#### Filters

Filters are combined with AND logic: a device must match every filter provided.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Filters by device name. Exact match. |
| `address` | string | Filters by IP address, hostname, or management URL. Exact match. |
| `active` | boolean | Filters by operational state. Accepted values: `true`, `false`. |
| `type` | string | Filters by device type. Exact match on a registered type. See [Device types](/v4-2/docs/pam-device-types). |
| `vendor` | string | Filters by vendor. Exact match on a registered vendor. See [Device vendors](/v4-2/docs/pam-device-vendors). |
| `product` | string | Filters by product. Exact match on a registered product. See [Device products](/v4-2/docs/pam-device-products). |
| `site` | string | Filters by site. Exact match on a registered site. See [Device sites](/v4-2/docs/pam-device-sites). |
| `domain_name` | string | Filters by domain name. Exact match. Omit this parameter to return devices regardless of domain association. |
| `tags` | array[string] | Filters by one or more tags. Use comma-separated values for OR logic (`tags=prod,database`); repeat the parameter for AND logic (`tags=prod&tags=database`). |
| `search` | string | Performs a free-text search across the device inventory. |

#### Sorting

`sort_by` accepts one or more fields in the format `field:asc` or `field:desc`. Multiple fields are comma-separated and processed left to right. The default direction is `asc`. Example: `sort_by=name:asc,type:desc`.

Sortable fields: `name`, `type`, `vendor`, `product`, `site`.

An unsupported field returns `422` (`api.sort.invalid_field`) with a hint listing the allowed fields; an unsupported direction returns `422` (`api.sort.invalid_direction`). For full sorting rules, see [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Field projection

`fields` restricts the response to the listed fields, using namespaced paths. Example: `fields=id,device.name,device.address`.

`data[].id` is always returned, whether or not the projection requests it. A path that doesn't exist in the list projection returns `422` (`api.fields.invalid`).

#### Pagination

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer | Page number. Minimum: `1`. Default: `1`. |
| `limit` | integer | Results per page. Minimum: `1`. Maximum: `200`. Default: `50`. |

A `limit` above `200` returns `422` (`api.pagination.limit.exceeded`), and `page=0` returns `422` (`api.request.invalid_param`). A page beyond the last one returns `200` with an empty `data` array and coherent pagination metadata.

---

### Example request

`GET` `{{url}}/api/v2/platform/devices?vendor=Oracle&active=true&sort_by=name:asc&limit=50`

---

## Response

```
HTTP/1.1 200 OK
```

Every response carries an `X-Request-Id` header, which correlates the request across Segura™ logs.

### Example response body

```
{
    "data": [
        {
            "id": "55",
            "device": {
                "name": "db-prod-01",
                "address": "10.10.10.10",
                "active": true,
                "type": "Server",
                "vendor": "Oracle",
                "product": "Oracle Linux VM",
                "site": "SP-DC1",
                "domain_name": "CORP",
                "tags": ["prod", "database"]
            }
        },
        {
            "id": "56",
            "device": {
                "name": "ws-dev-04",
                "address": "10.20.30.40",
                "active": false,
                "type": "Workstation",
                "vendor": "Microsoft",
                "product": "Windows Server 2022",
                "site": "NY-DC2",
                "domain_name": null,
                "tags": []
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 340,
            "total_pages": 7
        },
        "links": {
            "self": "/api/v2/platform/devices?page=1&limit=50",
            "first": "/api/v2/platform/devices?page=1&limit=50",
            "next": "/api/v2/platform/devices?page=2&limit=50",
            "last": "/api/v2/platform/devices?page=7&limit=50"
        }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of objects | List of devices matching the request filters. Returns an empty array when no device matches. |
| `data[].id` | string | Unique identification code of the device, assigned by Segura™ in [POST \| Create device](/v4-2/docs/api-v2-post-create-device). Always present in the response. |
| `data[].device` | object | Device attributes included in the list projection. |
| `data[].device.name` | string | Name that identifies the device. |
| `data[].device.address` | string | IP address, hostname, or management URL of the device. |
| `data[].device.active` | boolean | Indicates whether the device is active. |
| `data[].device.type` | string | Device type. Registered in [Device types](/v4-2/docs/pam-device-types). |
| `data[].device.vendor` | string | Device vendor. Registered in [Device vendors](/v4-2/docs/pam-device-vendors). |
| `data[].device.product` | string | Device product, bound to the vendor. Registered in [Device products](/v4-2/docs/pam-device-products). |
| `data[].device.site` | string | Site where the device is located. Registered in [Device sites](/v4-2/docs/pam-device-sites). |
| `data[].device.domain_name` | string | Domain associated with the device. Returns `null` when the device isn't linked to a domain. |
| `data[].device.tags` | array[string] | Tags associated with the device. Returns an empty array when no tags are configured. |
| `meta` | object | Pagination metadata and navigation links. |
| `meta.pagination` | object | Pagination details for the current result set. |
| `meta.pagination.page` | integer | Current page number. |
| `meta.pagination.limit` | integer | Maximum number of results per page. |
| `meta.pagination.total_items` | integer | Total number of devices matching the filters. |
| `meta.pagination.total_pages` | integer | Total number of pages. |
| `meta.links` | object | Navigation links for paginating through results. |
| `meta.links.self` | string | URL of the current page. |
| `meta.links.first` | string | URL of the first page. |
| `meta.links.next` | string | URL of the next page. |
| `meta.links.last` | string | URL of the last page. |

              Info

              

The list projection is a subset of the canonical model. Fields such as `criticality`, `owner`, `administrator_group`, `network_connector`, `enable_remote_app`, `connectivities`, and `session_settings` are returned only by the detail endpoint. To retrieve them, access [GET | List a device](/v4-2/docs/api-v2-get-list-a-device).

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.token.invalid` | The access token is missing or has expired. | Request a new access token. |
| `403` | `api.permission.denied` | The authorization doesn't have read permission to PAM Core resources. | Ask the administrator to check the authorization permissions in A2A, then generate a new token. |
| `422` | `api.pagination.limit.exceeded` | `limit` is above the maximum of `200`. | Lower `limit` to `200` or less and paginate through the results. |
| `422` | `api.request.invalid_param` | `page` is `0` or otherwise out of range. | Send a `page` value of `1` or higher. |
| `422` | `api.sort.invalid_field` | `sort_by` references a field outside the sortable set. | Sort by `name`, `type`, `vendor`, `product`, or `site`. |
| `422` | `api.sort.invalid_direction` | `sort_by` uses a direction other than `asc` or `desc`. | Use `field:asc` or `field:desc`. |
| `422` | `api.fields.invalid` | `fields` references a path outside the list projection. | Check the field paths against the response schema. |
| `429` | `rate_limit_exceeded` | The rate limit for the tenant, application, or endpoint was exceeded. | Wait the number of seconds given in the `Retry-After` header, then retry. |
| `500` | `api.internal.error` | Internal server error. | Contact the Segura™ support team. |

### Example error response

`422` a requested projection field doesn't exist:

```
{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the resource schema."
    }
}
```

### Authentication errors

| Message | Possible cause | Solution |
| --- | --- | --- |
| `Client authentication failed.` | Application authentication failure with the Segura™ server. | Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token. |
| `Invalid signature` | Failure in recognizing the client application URL. | Check the URL of the client application and resend the request. |
| `No route matched with those values.` | Missing authorization header in the API request. | Request a new access token. |
| `Request timed out.` | The request exceeded the timeout limit. | Check the connectivity between the source of the request and the Segura™ server. |

For the `403` versus `404` policy applied to resources outside your authorization scope, see [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Related documents

- [API v2 — Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [GET | List a device](/v4-2/docs/api-v2-get-list-a-device)
- [POST | Create device](/v4-2/docs/api-v2-post-create-device)
- [GET | List device connection status](/v4-2/docs/api-v2-get-device-connection-status)
- [How to manage authorizations in A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)
- [Device registration](/v4-2/docs/pam-device-device-registration)