---
title: "List connected print agents"
description: "List CloudPrint agents connected to the account and inspect their online status, version and update state."
---
# List connected print agents
List CloudPrint agents connected to the account and inspect their online status, version and update state.
GET/api/v1/agentsAPI version: v1operationId:listAgentsView as Markdown
## What this endpoint does
List CloudPrint agents connected to the account and inspect their online status, version and update state.
## Authentication
Send a short-lived access token in `Authorization: Bearer `.
**Required scopes:** `agents:read`
## Request
**Production base URL:** `https://public-api.cloudprint.me/api/v1/agents`
### Parameters
| Name | Location | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- | --- |
| `limit` | query | `integer` | no | Maximum number of agents to return. | min: 1; max: 100; default: `50` |
| `cursor` | query | `string \| null` | no | Cursor from the previous response next_cursor field. | — |
### Request body
This endpoint has no request body.
### Example requests
#### cURL
```bash
curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \
-H "Authorization: Bearer $ACCESS_TOKEN"
```
## Response
**HTTP status:** `200` — Account print agents
### Response fields
| Name | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `agents` | `array` | yes | Agents registered in the current CloudPrint account. | — |
| `next_cursor` | `string \| null` | yes | Opaque cursor for the next result page; send it back unchanged. | — |
### Example response
```json
{
"agents": [
{
"agent_id": "11111111-1111-4111-8111-111111111111",
"name": "Warehouse PC agent",
"status": "online",
"agent_instance_id": null,
"hostname": null,
"version": null,
"update": {
"status": "available",
"current_version": "0.1.0",
"latest_version": "0.1.1",
"minimum_supported_version": "0.1.0",
"channel": "stable",
"required": false
},
"last_seen_at": null
}
],
"next_cursor": null
}
```
## Errors
| HTTP status | Description |
| --- | --- |
| `401` | OAuth bearer token is missing or invalid |
| `403` | OAuth bearer token does not include agents:read |
| `422` | Pagination parameters are invalid |
| `429` | Rate limit exceeded |
| `500` | Unexpected error |
## Integration guidance
- Treat agent status as operational information, not as a printer routing key.
- Show update state to operators before investigating printer or document failures.
## Related documentation