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 processing and its results are available.

What happens: Results can be retrieved via the API.

Note: Completed means result processing finished, not that every shot came back. Results carry their own status — Completed, PartialComplete, Failed, or Cancelled — and a task with a Completed status can carry a PartialComplete result when the data landed above the completion threshold but short of 100%. See Retrieve Results for what each result status means, or your deployment's own API documentation for the generated schema.

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"
  ]
}