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.
A valid OAuth 2.0 access token. For more information, access 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.

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.

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.
`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.
`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.