API reference · 4 endpoints

Async operations

Track, retry, and cancel asynchronous work started by retain and other endpoints.

GET/v1/default/namespaces/{namespace_id}/operations

List async operations

Get a list of async operations for a specific agent, with optional filtering by status and operation type. Results are sorted by most recent first.

Parameters

namespace_idstringpathrequired
statusstring | nullquery

Filter by status: pending, processing, completed, failed, or cancelled

typestring | nullquery

Filter by operation type: retain, consolidation, refresh_automation, file_convert_retain, webhook_delivery

limitintegerquery

Maximum number of operations to return

offsetintegerquery

Number of operations to skip

exclude_parentsbooleanquery

Exclude parent batch operations from results

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/operations" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "namespace_id": "user123",
  "limit": 20,
  "offset": 0,
  "operations": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "task_type": "retain"
    }
  ],
  "total": 150
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/operations/{operation_id}

Get operation status

Get the status of a specific async operation. Returns 'pending', 'completed', or 'failed'. Completed operations are removed from storage, so 'completed' means the operation finished successfully.

Parameters

namespace_idstringpathrequired
operation_idstringpathrequired
include_payloadbooleanquery

Include the raw task payload (submission params) in the response. May be large.

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/operations/ope_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "completed_at": "2024-01-15T10:31:30Z",
  "created_at": "2024-01-15T10:30:00Z",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "refresh_automations",
  "status": "completed",
  "updated_at": "2024-01-15T10:31:30Z"
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

DELETE/v1/default/namespaces/{namespace_id}/operations/{operation_id}

Cancel a pending async operation

Cancel a pending async operation by removing it from the queue

Parameters

namespace_idstringpathrequired
operation_idstringpathrequired
curl -X DELETE "https://api.illumina.sh/v1/default/namespaces/demo/operations/ope_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/operations/{operation_id}/retry

Retry a failed async operation

Re-queue a failed async operation so the worker picks it up again

Parameters

namespace_idstringpathrequired
operation_idstringpathrequired
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/operations/ope_123/retry" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

Search docs

Search the documentation