List connected print agents
List CloudPrint agents connected to the account and inspect their online status, version and update state.
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 <access_token>.
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 resources to return on one page. | min: 1; max: 100; default: 50 |
cursor | query | string | null | no | Opaque cursor for the requested result page; reuse it unchanged. | — |
X-Request-Id | header | string | no | Optional request identifier for tracing; CloudPrint returns a safe value in the response header. | maxLength: 128; example: "order-100045-attempt-1" |
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": "string",
"hostname": "string",
"version": "string",
"build_flavor": "standard",
"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": "2026-08-06T12:00:00Z"
}
],
"next_cursor": "string"
}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
Local Printer API for web and SaaS applicationsConnect a web or SaaS backend to local printers through CloudPrint Agent, discover printer queues via API and route jobs by stable printer ID.List available printersList printers visible through connected CloudPrint agents and select a stable printer ID for a workflow.Troubleshoot agents, printers and print jobsDiagnose CloudPrint integration problems by request ID, job status, agent connectivity, printer capabilities and API error code.