Migrating to API v0.4
See what’s new in API v0.4 and how to migrate from v0.3.
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
Breaking Changes Requiring Updates
- Result retrieval: Must update to use new probabilities endpoint - change from parsing
output
field to callingGET /jobs/{UUID}/results/probabilities
- 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
Jobs
Enhanced Results Structure
Job results are now organized into dedicated sub-endpoints with results.probabilities.url
field instead of direct output
field, requiring updates to result retrieval logic to use the new GET /jobs/{UUID}/results/probabilities
endpoint.
v0.3: Job results included directly in job response with output
field
v0.4: Results moved to dedicated endpoint structure with results.probabilities.url
field
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.3 Endpoints:
GET /characterizations/{backend}/all
GET /characterizations/{backend}/current
GET /characterizations/{characterization_id}
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.