> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

### 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 `type`s 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.