Long Running Operations

Overview

In some cases, you might need to perform bulk operations that take a significant amount of time to complete. To ensure a smooth and efficient process, our APIs handle these operations asynchronously.

Asynchronous Bulk APIs

When you trigger a long-running operation, such as the Bulk Retire Devices API, the server will not keep the connection open until the operation is complete. Instead, it will return an immediate response indicating that the operation has been accepted for processing.

Bulk device retirement is currently the only asynchronous operation in the public API.

Expected Response

Upon initiating a long-running operation, you will receive an HTTP 202 Accepted response. This status code indicates that the request has been received and understood, and that the processing is continuing asynchronously.

Response Body

The Location response header and the location field of the response body both contain the absolute URL of the operation, which you can use to check its status and result:

HTTP/1.1 202 Accepted
Location: https://api.sensos.io/v1/accounts/2ce1a86e-7331-4542-b1f8-085ac1225cff/operations/ed37a334-ca01-4bb3-9139-f2892915a306

{
  "location": "https://api.sensos.io/v1/accounts/2ce1a86e-7331-4542-b1f8-085ac1225cff/operations/ed37a334-ca01-4bb3-9139-f2892915a306"
}

Fetching Operation Results

To check the status of your long-running operation, make a GET request to the provided location (see Get Operation). This will return information about the current status of the operation and, once it has finished, its result.

Example Status Check Request:

GET https://api.sensos.io/v1/accounts/2ce1a86e-7331-4542-b1f8-085ac1225cff/operations/ed37a334-ca01-4bb3-9139-f2892915a306
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Example Status Check Response:

{
  "id": "ed37a334-ca01-4bb3-9139-f2892915a306",
  "createdTime": "2026-09-14T08:30:00.1234567Z",
  "status": "Running",
  "type": "DeviceRetirement"
}

status is one of:

Once the operation is complete, the status will change to Completed.

Example Completed Response:

{
  "id": "ed37a334-ca01-4bb3-9139-f2892915a306",
  "createdTime": "2026-09-14T08:30:00.1234567Z",
  "status": "Completed",
  "type": "DeviceRetirement"
}

Error Handling

If the operation fails for some of the devices, its status is Failed and error describes what went wrong. error.details is an array with one entry per failed device: id is the device ID, and message (and, when available, code) explain why it failed. Devices that are not listed in error.details were processed successfully.

Example Error Response:

{
  "id": "ed37a334-ca01-4bb3-9139-f2892915a306",
  "createdTime": "2026-09-14T08:30:00.1234567Z",
  "status": "Failed",
  "type": "DeviceRetirement",
  "error": {
    "message": "Operation failed for 1 entities",
    "details": [
      {
        "id": "860000000000001",
        "message": "Failed to retire device 860000000000001"
      }
    ]
  }
}

Best Practices

• Polling Frequency: Avoid excessive polling. Implement an exponential backoff strategy to check the operation status.
• Error Handling: Implement robust error handling to manage various status responses and errors.
• Timeouts: Set appropriate timeouts for your requests to avoid hanging operations in your application.