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

1. Result retrieval: Must update to use new probabilities endpoint - change from parsing output field to calling GET /jobs/{UUID}/results/probabilities
2. Characterization URLs: All characterization endpoints require URL updates to new nested structure under /backends/
3. Date parameters: Update timestamp formats in characterization filtering from Unix timestamps to ISO date strings
4. 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.