Skip to main content
This guide covers the key changes when upgrading from IonQ’s API v0.3 to v0.4. The new version introduces several structural improvements and new features while maintaining compatibility for most existing workflows.

​
Compatibility Notes

​
Backward Compatibility

  • Base functionality: Core job submission and retrieval workflows remain similar
  • Authentication: API key authentication unchanged
  • Job lifecycle: Job statuses and workflow unchanged
  • Circuit formats: Input circuit formats remain compatible

​
Major breaking changes

  • Result retrieval:
    • Use GET /jobs/{UUID}/results/probabilities instead of /jobs/{UUID}/results,
    • URLs are now in results.probabilities.url on the Job object instead of results_url
  • Characterization URLs: All characterization endpoints require URL updates to new nested structure under /backends/
  • Date parameters: Update timestamp formats in characterization filtering from Unix timestamps to ISO date strings
  • Response parsing: Update code to handle new response field structure including results.probabilities.url field

​
Changes to jobs

​
Job Types

A job’s type determines the schemas for the input, output, results, and settings of a Job. We’re starting to support more than just circuits, and in preparation are expanding our support for different types of jobs. This field tells our internal services how to process this workload, and at launch we’re only supporting ionq.circuit.v1 which is designed to be largely compatible with legacy circuit submissions, but expect to see workload-specific schemas soon for Functions and external integrations.

​
Job names are more restrictive

Job names now only allow letters (a-zA-Z) and numbers (0-9), spaces, hyphens (-), or underscores (_).

​
More Job data

We’ve added output, results, and stats to the Jobs object, allowing us to add more (and more types of!) data to our Jobs.
  • results of a circuit are its measurement data, and as we add other types of jobs, things like functions may have different results such as a solution or minimum_value instead.
  • output is data passed from sub-processors that handled the job along the way. Check out output.compilation for example, which is now starting to add additional diagnostic data from our compiler.
  • stats is reporting some high-level data about the job. gate_counts contains the number of single-qubit (1q) and two-qubit (2q) gates that were submitted, and kwh reports the estimated energy consumed during QPU execution (always zero for simulator jobs).

​
New job cost endpoint

v0.4 introduces GET /jobs/{UUID}/cost for retrieving detailed billing information including estimated and actual costs in USD, enabling better cost tracking and budget management at the job level.

​
Response field additions

Job responses now include additional fields: child_job_ids, session_id, and timing prediction fields for improved job monitoring and workflow management.

​
Endpoint naming updates

  • Job result retrieval: GET /jobs/{UUID}/output → GET /jobs/{UUID}/results/probabilities

​
Backends

​
Restructured Characterizations API

Characterizations now use a more intuitive REST structure with endpoints nested under backends and pagination support. v0.4 Endpoints:
  • GET /backends/{backend}/characterizations (with pagination)
  • GET /backends/{backend}/characterizations/{characterization_id}
  • GET /backends/{backend} (individual backend details)

​
Enhanced Backend Information

Backend responses now include degraded status flag and characterization_id linking for better backend selection and status monitoring capabilities.

​
Date Parameter Format Changes

Characterization filtering now uses ISO date strings (e.g., start=2025-12-31) instead of Unix timestamps (e.g., start=1585713600000).

​
Query Parameter Enhancements

Characterization endpoints now include limit and page parameters for improved pagination control alongside the updated date string format.