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 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
Connect an agent and select a printerInstall the CloudPrint agent, discover local printer queues and choose a stable printer ID based on its advertised capabilities.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.