This feature is in Beta. It's only available on certain tenants at this time.
In this article, we will be checking multiple device’s status for a converge operation. With this API guide, you can also check on which devices failed to converge.
Step 1: Fire the converge operation to consolidated list of devices
Option 1: From the console:
First, use a filter to find all devices that are managed by blueprints and in the provisioned state. Not every tenant will need to filter by blueprints.
Then, select all applicable devices.
Then click on Actions > Converge.
Option 2: From the API:
If you prefer, you can alternatively fire a command from the API. You might use this command instead of the console if you have a list of device IDs you want to target.
In the body of the request, use the device ID to specify which devices you want to converge.
Note: Device ID refers to a device’s API ID.
Request
POST https://{tenant}-api.esper.cloud/api/v0/operations/
Body
{
"operation_type":"CONVERGE",
"arguments":{},
"schedule_type":"IMMEDIATE",
"operation_device_query": {
"device_ids":"device_id_1, device_id_2,...., device_id_50000"
}
}
Response
{
"content": {
"id": "3cf77731-81b3-4629-b71b-ecb2a772fbaa",
"tenant_id": "27c39cbc-c23e-40e1-a5cc-39524b3d677b",
"operation_type": "CONVERGE",
"state": "CREATED",
"schedule_type": "IMMEDIATE",
"schedule_args": {},
"device_query": {
"device_request": {
"state": "1",
"group_multi": "c8f5127d-e923-456b-ac73-2200760bf462,92ecf3f6-758e-4cd3-9d2a-cc02317125d3,ded04dce-ca9b-489a-8ab8-18cf91fc50b0,9f155a96-029b-4cfc-a463-fca02b72938f"
}
},
"arguments": {},
"reason": null,
"created_by": "1",
"updated_by": "1",
"created_at": "2025-02-25T04:30:25.439546176Z",
"updated_at": "2025-02-25T04:30:25.439546176Z",
"operation_activity": [
{
"operation_state": "CREATED",
"created_at": "2025-02-25T04:30:25.438840999Z"
}
],
"operation_stats": {
"resolved_device_count": 0,
"dispatched_device_count": 0,
"dispatch_failed_count": 0,
"failed_device_count": 0,
"success_device_count": 0
}
}
}
The operation_stats body is a placeholder for the operation status changes, so it's expected that you'll see 0s. In Step 2, you will get the values for each field with the operation status request.
Copy the ID from the response. This will be your Operation ID. In the above example, the Operation ID is 3cf77731-81b3-4629-b71b-ecb2a772fbaa.
Tip: You can query this list using the following operation codes:
| Operation State Codes | |
| Operation | Code |
| OPERATION_CREATED | 10 |
| OPERATION_RESOLVING | 20 |
| OPERATION_RESOLVED | 30 |
| OPERATION_DISPATCHING | 40 |
| OPERATION_DISPATCHED | 50 |
| OPERATION_PROCESSING | 60 |
| OPERATION_COMPLETED | 70 |
| OPERATION_SUCCESS | 80 |
| OPERATION_FAILURE | 90 |
| OPERATION_SCHEDULED | 100 |
| OPERATION_CANCELLED | 110 |
| OPERATION_TIMEOUT | 120 |
Step 2: Get the operation status and the device count
Use this API to get the device count corresponding to the device operation status.
Request
GET https://{tenant}-api.esper.cloud/api/v0/operations/{operation_id}
Response
{
"content": {
"id": "3cf77731-81b4-4629-b71b-ecb2a772fbac",
"tenant_id": "27c39cbc-c23e-40e1-a5cc-39524b3d677b",
"operation_type": "CONVERGE",
"state": "SUCCESS",
"schedule_type": "IMMEDIATE",
"schedule_args": null,
"device_query": {
"device_ids": "b86db2b1-e9b9-4847-ab1e-9944ad4d6084, 0469bad5-e1d2-4b36-a6d1-e0987e09fd5c"
},
"arguments": {},
"reason": "Operation completed successfully",
"created_by": "1",
"updated_by": "1",
"created_at": "2025-01-29T20:43:37.49864Z",
"updated_at": "2025-01-29T20:44:26.354959Z",
"operation_activity": [
{
"created_at": "2025-01-29T20:43:37.497916763Z",
"operation_state": "CREATED"
},
{
"created_at": "2025-01-29T20:43:39.665132943Z",
"operation_state": "QUERY INITIATED"
},
{
"created_at": "2025-01-29T20:43:39.672152591Z",
"operation_state": "QUERY RESOLVED"
},
{
"created_at": "2025-01-29T20:43:40.714194084Z",
"operation_state": "DISPATCHING"
},
{
"created_at": "2025-01-29T20:43:40.809076981Z",
"operation_state": "DISPATCHED"
},
{
"created_at": "2025-01-29T20:43:41.014738718Z",
"operation_state": "PROCESSING"
},
{
"created_at": "2025-01-29T20:44:26.35433346Z",
"operation_state": "FAILED"
}
],
"operation_stats": {
"resolved_device_count": 50000,
"dispatched_device_count": 50000,
"dispatch_failed_count": 0,
"failed_device_count": 42,
"success_device_count": 49958
}
}
}
For example, to find all the devices that failed the converge operation, use https://{tenant}--api.esper.cloud/api/v0/operations/?state=90.
Understanding the status
If all devices are able to complete the operation, the state will show Success. If this was your goal, you can stop here.
However, if even one device fails to complete the operation, the state will show FAILED. Go to Step 3 to get the finer details of every operation and the devices that failed to converge.
Step 3: Get the device operations
Get a list of devices the operation targeted and their status.
Request
GET https://{tenant}-api.esper.cloud/api/v0/operations/{operation_id}/devices?state=60&ordering=created_atThe list will be ordered in descending order from the most recent operation using the created_at query.
In this example, we used 60 to target operation failures.
| Device Operation State Codes | |
| Device Operation State | Code |
| DEVICE_OPERATION_CREATED | 10 |
| DEVICE_OPERATION_INITIATED | 20 |
| DEVICE_OPERATION_DISPATCHED | 30 |
| DEVICE_OPERATION_PROCESSING | 40 |
| DEVICE_OPERATION_SUCCESS | 50 |
| DEVICE_OPERATION_FAILURE | 60 |
| DEVICE_OPERATION_CANCELLED | 70 |
| DEVICE_OPERATION_TIMEOUT | 80 |
| DEVICE_OPERATION_COMPLETED | 90 |
Response
"count": 42,
"prev": null,
"next": "https://sample-api.esper.cloud/api/v0/operations/67f30b86-6761-4c29-95b2-830d5cd7b102/devices/?ordering=-created_at&state=60&offset=10",
"results": [
{
"id": "aee71f5d-e812-456e-bf41-22e914328781",
"operation_id": "67f30b86-6761-4c29-95b2-830d5cd7b102",
"device_id": "e44f224f-c017-4bd9-98fe-b1375a4c903d",
"state": "FAILED",
"reason": "",
"created_at": "2025-01-29T07:18:43.931966Z",
"updated_at": "2025-01-29T07:59:57.247004Z",
"device_operation_activity": [
{
"created_at": "2025-01-29T07:18:43.460696541Z",
"device_operation_state": "CREATED"
},
{
"created_at": "2025-01-29T07:24:29.975352931Z",
"device_operation_state": "INITIATED"
},
{
"created_at": "2025-01-29T07:24:30.000584309Z",
"device_operation_state": "DISPATCHED"
},
{
"created_at": "2025-01-29T07:59:42.522462048Z",
"device_operation_state": "PROCESSING"
},
{
"created_at": "2025-01-29T07:59:57.246241106Z",
"device_operation_state": "FAILED"
}
]
},
{
"id": "9246274f-9a75-4349-83de-817c2b55fdce",
"operation_id": "49f91c35-d588-445f-8411-974c8ce72450",
"device_id": "e16f7564-b273-41bd-8080-6de6bc73a856",
"state": "FAILED",
"reason": "",
"created_at": "2025-01-29T07:18:43.900943Z",
"updated_at": "2025-01-29T07:53:18.556762Z",
"device_operation_activity": [
{
"created_at": "2025-01-29T07:18:43.460696541Z",
"device_operation_state": "CREATED"
},
{
"created_at": "2025-01-29T07:23:33.382522136Z",
"device_operation_state": "INITIATED"
},
{
"created_at": "2025-01-29T07:23:33.467621961Z",
"device_operation_state": "DISPATCHED"
},
{
"created_at": "2025-01-29T07:53:02.444349113Z",
"device_operation_state": "PROCESSING"
},
{
"created_at": "2025-01-29T07:53:18.556224586Z",
"device_operation_state": "FAILED"
}
]
},
[...]
}
Step 4: Find out more information and converge again
You now have a list of devices that failed to converge.
You can add their IDs to the POST operations API to fire another converge.
Before doing so, we recommend checking the device’s connectivity and other information by using the Get last seen API.
If the last seen time was greater than thirty minutes, the device may no longer be connected to the Esper cloud.
Request
GET https://{foo}-api.esper.cloud/api/device/v0/heartbeat/{id}/Response
{
"code": 200,
"message": "success",
"content": {
"device_id": "e16f7564-b273-41bd-8080-6de6bc73a856",
"timestamp": "2025-03-03T20:25:40.375015Z",
"status": 0
}
}
Use the API to understand device status for converge operations.