---
title: "GET | List all Network Connector agents"
slug: "api-v2-get-list-all-network-connector-agents"
updated: 2026-10-14T16:25:50Z
published: 2026-10-14T16:25:50Z
canonical: "docs.senhasegura.io/api-v2-get-list-all-network-connector-agents"
---

> ## 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 Network Connector agents

## Description

List the agents of the Network Connector with their identification codes, names, ports, status, and fingerprints. Returns a paginated, filterable list.

Use the `id` of an agent in the `network_connector_id` field to link a device to that agent.

By default, the list includes only active agents. To list deactivated agents, use the `active` filter.

Without the `active` filter, every `id` the list returns is accepted by the `network_connector_id` field of a device. A device does not accept a deactivated agent. In the device request, send the `id` as an integer.

---

## Prerequisites

- An application with the **PAM resource permission** set to **Read-only** or **Read and write**, granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A for API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).

---

## Request

`GET` `/api/v2/platform/network-connector/agents`

### Query parameters

All query parameters are optional. Without parameters, the endpoint returns the first 50 active agents, sorted by name.

#### Filters

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Filters by agent name. Matches the name exactly. Add the `_contains`, `_starts_with`, or `_ends_with` suffix for a partial match. Example: `name_contains=sp`. |
| `port` | string | Filters by agent port. Matches the port exactly. Accepts the same suffixes as `name`. |
| `search` | string | Searches for a text fragment in `name` and `port`. When you send several terms separated by spaces, each term must appear. |
| `active` | boolean | Filters by agent status. `true` returns active agents and `false` returns deactivated agents. Default: `true`. To get all agents, send one request with `active=true` and another with `active=false`. |

In a filter, values separated by commas work as OR. Example: `port=30001,30002`. Different parameters work as AND.

#### Sorting

| Field | Type | Description |
| --- | --- | --- |
| `sort_by` | string | Sorts the result set in the format `field:asc` or `field:desc`. Accepted fields: `id`, `name`, and `port`. Default: `name:asc`, then `id:asc`. |

For full sorting rules, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

#### Pagination

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

This endpoint supports only page-based pagination. It does not accept `cursor`.

#### Field projection

| Field | Type | Description |
| --- | --- | --- |
| `fields` | string | Restricts the response to the listed fields. Accepts `id`, `network_connector_agent.name`, `network_connector_agent.port`, `network_connector_agent.active`, and `network_connector_agent.fingerprint`. The `id` field is always returned. |

Request each field by its full path. Requesting the whole object with `fields=network_connector_agent` returns `422`.

For the full field projection syntax, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

### Example request

`GET` `{{url}}/api/v2/platform/network-connector/agents`

---

## Response

```
HTTP/1.1 200 OK
```

The list does not return an `ETag` header.

### Example response body

```
{
    "data": [
        {
            "id": "2",
            "network_connector_agent": {
                "name": "agent-rj-01",
                "port": "30001",
                "active": true,
                "fingerprint": "EXAMPLE-FINGERPRINT-0001"
            }
        },
        {
            "id": "5",
            "network_connector_agent": {
                "name": "agent-sp-01",
                "port": "30002",
                "active": true,
                "fingerprint": "EXAMPLE-FINGERPRINT-0002"
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 50,
            "total_items": 2,
            "total_pages": 1
        },
        "links": {
            "self": "/api/v2/platform/network-connector/agents"
        }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of objects | Agents matching the request filters. Without the `active` filter, returns only active agents. Returns an empty array when no agent matches. |
| `data[].id` | string | Unique identification code of the agent, returned as a string. Use this value in the `network_connector_id` field of a device. |
| `data[].network_connector_agent` | object | Attributes of the agent. |
| `data[].network_connector_agent.name` | string | Name of the agent. |
| `data[].network_connector_agent.port` | string | Port of the agent, returned as a string. Can be `null`. |
| `data[].network_connector_agent.active` | boolean | `true` when the agent is active, `false` when it is deactivated. |
| `data[].network_connector_agent.fingerprint` | string | Value used to install the agent. Store it securely and share it only with whoever installs the agent. Can be `null`. |
| `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 agents matching the filters. |
| `meta.pagination.total_pages` | integer | Total number of pages. |
| `meta.links` | object | Navigation links for the result set. |
| `meta.links.self` | string | URL of the current page. |
| `meta.links.next` | string | URL of the next page. Returned only when there is a next page. |
| `meta.links.prev` | string | URL of the previous page. Returned only from page 2 onward. |

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `400` | `api.request.bad_request` | The request sent an unknown query parameter. | Check the parameter names in [Query parameters](/docs/api-v2-get-list-all-network-connector-agents#query-parameters). |
| `404` | No specific code | The Network Connector does not exist in the environment. | Check that the Network Connector is set up in Segura®. |
| `422` | `api.fields.invalid` | The `fields` parameter requested a field that does not exist. | Check the field names in [Field projection](/docs/api-v2-get-list-all-network-connector-agents#field-projection). |
| `422` | No specific code | The `fields` parameter requested the whole `network_connector_agent` object. | Request each field by its full path, such as `network_connector_agent.name`. |
| `422` | `api.enum.invalid_value` | The `active` filter received a value other than `true` or `false`. | Send `active=true` or `active=false`. |
| `422` | `api.pagination.limit.exceeded` | The `limit` value is greater than `200`. | Send a `limit` between `1` and `200`. |
| `422` | `api.sort.invalid_field` | The `sort_by` parameter used a field other than `id`, `name`, or `port`. | Sort by `id`, `name`, or `port`. |
| `422` | `api.sort.invalid_direction` | The `sort_by` parameter used a direction other than `asc` or `desc`. | Use `:asc` or `:desc`. |
| `422` | No specific code | The `page` or `limit` value is lower than `1` or is not a number. | Send a positive integer. |

For authentication and permission errors and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).

---

## Related documents

- [GET | List a Network Connector agent by [id]](/v4-2/docs/api-v2-get-list-a-network-connector-agent)
- [GET | List the Network Connector](/v4-2/docs/api-v2-get-list-the-network-connector)
- [POST | Create Network Connector agent](/v4-2/docs/api-v2-post-create-network-connector-agent)
- [POST | Activate Network Connector agent](/v4-2/docs/api-v2-post-activate-network-connector-agent)
- [POST | Deactivate Network Connector agent](/v4-2/docs/api-v2-post-deactivate-network-connector-agent)
- [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [About applications and authorizations in A2A](/v4-2/docs/a2a-about-applications-and-authorizations)