Skip to content

Task Lifecycle

Understanding the task lifecycle helps you monitor execution progress and troubleshoot issues.

Task States

A task progresses through several states from submission to completion:

stateDiagram-v2
    [*] --> Created: Submit
    Created --> PayloadProcessing: Picked up
    PayloadProcessing --> Scheduled: Compiled
    PayloadProcessing --> PayloadProcessingError: Compilation/validation error
    Scheduled --> ExecutionStarted: QPU begins
    ExecutionStarted --> ExecutionCompleted: QPU finished
    ExecutionCompleted --> Completed: Results ready
    ExecutionStarted --> Failed: Execution error
    Scheduled --> Cancelled: User cancels
    Created --> Cancelled: User cancels
    PayloadProcessing --> Cancelled: User cancels
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]
    PayloadProcessingError --> [*]

State Descriptions

Created

The task has been created and is waiting to be picked up for processing.

What happens: Task is stored in the database and added to the processing queue.

PayloadProcessing

The task is going through compilation, validation, and optimization.

What happens:

  • Task definition is verified
  • Payload structure is validated
  • Quantum program is compiled to Flair
  • Circuit optimizations are applied

Scheduled

The compiled task has been submitted to the QPU queue.

What happens: Task joins the hardware execution queue and waits for QPU availability.

ExecutionStarted

The QPU has started executing the task.

What happens:

  • Hardware is configured for the task
  • Program is executed for the requested number of shots
  • Raw measurement data is being collected

Note: Partial results may be available during this state.

ExecutionCompleted

The QPU has completed execution, but results may still be post-processing.

What happens:

  • Raw results are transformed to standard formats
  • Result aggregation is performed

Note: Partial results are available during this state.

Completed

The task finished successfully and all results are available.

What happens: Full results can be retrieved via the API.

Error States

Cancelled

The user cancelled the task.

PayloadProcessingError

An error occurred during compilation or validation.

What happens: Error details are stored with the task for debugging.

Failed

An error occurred during processing or execution.

What happens: Error details are stored with the task for debugging.

Checking Task Status

QLAM Shell

qsh tasks get <task-id>

Direct API

curl -X GET "https://api.example.quera.com/v2/{qpu_mode}/tasks/{task_id}" \
  -H "Authorization: Bearer $TOKEN"

Response includes the current state:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "task_status": "ExecutionStarted",
  "definition_id": "550e8400-e29b-41d4-a716-446655440001",
  "compilation_id": "916ae6d7-f64f-4a2a-8ff9-a40f07f487bc",
  "created_by": "user-uuid",
  "created_date": "2026-01-26T10:00:00Z",
  "updated_date": "2026-01-26T10:01:30Z",
  "error_reasons": []
}

Handling Failures

When a task fails, the error_reasons array contains details:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "task_status": "PayloadProcessingError",
  "definition_id": "550e8400-e29b-41d4-a716-446655440001",
  "created_by": "user-uuid",
  "created_date": "2026-01-26T10:00:00Z",
  "updated_date": "2026-01-26T10:01:30Z",
  "error_reasons": [
    "Unsupported gate: ccx - The ccx (Toffoli) gate is not supported in this mode"
  ]
}