Jobs contain a circuit to be executed on a QPU, and in the case of multicircuit jobs, multiple circuits are being submitted in a single job payload. The advantage of this approach is that it simplifies the submission process, allowing for example, all of the circuits of a gradient calculation to be submitted in a single HTTP request, instead of over hundreds.

When submitting work from a local environment with a poor internet connection, this can also help overcome job submissions failing intermittently from network issues.

To ensure smooth processing, please format your quantum programs in ionq.circuit.v0 as demonstrated below.

​
Creating a Multicircuit Job

Below is a JSON object that describes a multicircuit job for IonQ’s simulator. This job includes two distinct circuits:

{
  "target": "simulator",
  "shots": 1024,
  "name": "Multicircuit Job Example",
  "input": {
    "format": "ionq.circuit.v0",
    "gateset": "qis",
    "qubits": 3,
    "circuits": [
      {
        "name": "Circuit 1",
        "circuit": [
          {
            "gate": "rz",
            "targets": [0],
            "rotation": -0.7853981633974474
          },
          {
            "gate": "ry",
            "targets": [0],
            "rotation": 3.141592653589793
          }
        ]
      },
      {
        "name": "Circuit 2",
        "circuit": [
          {
            "gate": "h",
            "targets": [1]
          },
          {
            "gate": "x",
            "targets": [2],
            "controls": [1]
          }
        ]
      }
    ]
  }
}

​
Submitting the Job

To submit this multicircuit job to IonQ, use the following curl command. Make sure to replace your-api-key with your actual API key:

curl -X POST "https://api.ionq.co/v0.3/jobs" \
  -H "Authorization: apiKey your-api-key" \
  -H "Content-Type: application/json" \
  -d '{...}'  # JSON data from the creation step

​
Expected Response

You should receive a JSON response containing the job ID and status, similar to this:

{
  "id": "unique-job-id",
  "status": "ready",
  "request": 1234567890
}

​
Retrieving Job Results

Once the job is complete, fetch the results using the job’s UUID provided in the job submission response:

curl "https://api.ionq.co/v0.3/jobs/unique-job-id/results" \
  -H "Authorization: apiKey your-api-key"

​
Result Example

{
  "circuit1-uuid": {
    "0": 0.5,
    "6": 0.5
  },
  "circuit2-uuid": {
    "1": 1.0
  }
}

Each UUID represents a circuit within your job, and the results show the probability distribution of the qubit measurements.

If you are interested in implementing these steps using the Qiskit SDK, check out this detailed multicircuit guide with Qiskit and IonQ.

Jobs contain a circuit to be executed on a QPU, and in the case of multicircuit jobs, multiple circuits are being submitted in a single job payload. The advantage of this approach is that it simplifies the submission process, allowing for example, all of the circuits of a gradient calculation to be submitted in a single HTTP request, instead of over hundreds.

When submitting work from a local environment with a poor internet connection, this can also help overcome job submissions failing intermittently from network issues.

To ensure smooth processing, please format your quantum programs in ionq.circuit.v0 as demonstrated below.

​
Creating a Multicircuit Job

Below is a JSON object that describes a multicircuit job for IonQ’s simulator. This job includes two distinct circuits:

{
  "target": "simulator",
  "shots": 1024,
  "name": "Multicircuit Job Example",
  "input": {
    "format": "ionq.circuit.v0",
    "gateset": "qis",
    "qubits": 3,
    "circuits": [
      {
        "name": "Circuit 1",
        "circuit": [
          {
            "gate": "rz",
            "targets": [0],
            "rotation": -0.7853981633974474
          },
          {
            "gate": "ry",
            "targets": [0],
            "rotation": 3.141592653589793
          }
        ]
      },
      {
        "name": "Circuit 2",
        "circuit": [
          {
            "gate": "h",
            "targets": [1]
          },
          {
            "gate": "x",
            "targets": [2],
            "controls": [1]
          }
        ]
      }
    ]
  }
}

​
Submitting the Job

To submit this multicircuit job to IonQ, use the following curl command. Make sure to replace your-api-key with your actual API key:

curl -X POST "https://api.ionq.co/v0.3/jobs" \
  -H "Authorization: apiKey your-api-key" \
  -H "Content-Type: application/json" \
  -d '{...}'  # JSON data from the creation step

​
Expected Response

You should receive a JSON response containing the job ID and status, similar to this:

{
  "id": "unique-job-id",
  "status": "ready",
  "request": 1234567890
}

​
Retrieving Job Results

Once the job is complete, fetch the results using the job’s UUID provided in the job submission response:

curl "https://api.ionq.co/v0.3/jobs/unique-job-id/results" \
  -H "Authorization: apiKey your-api-key"

​
Result Example

{
  "circuit1-uuid": {
    "0": 0.5,
    "6": 0.5
  },
  "circuit2-uuid": {
    "1": 1.0
  }
}

Each UUID represents a circuit within your job, and the results show the probability distribution of the qubit measurements.

If you are interested in implementing these steps using the Qiskit SDK, check out this detailed multicircuit guide with Qiskit and IonQ.