Direct API Submissions

Most users will submit jobs and interact with IonQ through an SDK like Qiskit, but in some instances direct API submission is needed. This guide walks you through the basics of using the IonQ Quantum Cloud to write and run quantum programs: using the Quantum Cloud API to specify a quantum circuit, submitting it as a job, and then accessing the results.

​

Before you begin

You’ll need an account on the IonQ Quantum Cloud, and you’ll need to create an API key. We also have a guide about setting up and managing your API keys if you need some help.

This guide assumes that you have followed these instructions and have saved your API key as a local environment variable named IONQ_API_KEY.

​

Writing a quantum circuit

We’ll need to create a quantum circuit to submit as your first job. Let’s use a simple GHZ state using three qubits, first applying a Hadamard gate to a single qubit, and then using it as the control qubit for a series of controlled-not gates on the other two.

Diagrammed, a three-qubit GHZ circuit looks like this:

In IonQ’s language-agnostic JSON circuit representation, the circuit looks like this:

{
  "input": {
    "qubits": 3,
    "circuit": [
      {
        "gate": "h",
        "target": 0
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 1
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 2
      }
    ]
  }
}

​

Submit your quantum circuit as a Job

Now we’re ready to submit this circuit as a job. To submit the job, we need to add a few additional parameters to our circuit: the language, the number of shots, where we want the job to run (ex: simulator or qpu.aria-1) and, optionally, a name for your own reference.

In this case, we’ll submit a job to the simulator so that we get our results quickly, and we’ll use the Aria noise model:

{
  "name": "Hello many worlds!",
  "shots": 1024,
  "target": "simulator",
  "noise": {
    "model": "aria-1"
  },
  "input": {
    "qubits": 3,
    "circuit": [
      {
        "gate": "h",
        "target": 0
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 1
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 2
      }
    ]
  }
}

Paste this in your text editor of choice and then save it using a memorable name—something like ghz-job.json.

Now, we’re ready to submit our job to the IonQ Cloud API. To do that, we’ll POST our JSON job body to the job creation route, with two headers: one for authorization with the API key we created earlier, and one to tell the API that our job body is JSON formatted. Since we want to see something quickly, we’ll submit to "target": "simulator" for now.

curl -X POST "https://api.ionq.co/v0.3/jobs" \
    -H "Authorization: apiKey $IONQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d @ghz-job.json

Which will return something like:

{
    "id": "7135ca98-176f-48c9-8616-8f53ec505028",
    "status": "ready",
    "request": 1718302151
}

And there it goes! The id can now be used to cancel it, get the status, or retrieve results.

​

Retrieve the job results

To retrieve the job, we can now GET it at its own resource URL, determined by the job id:

curl "https://api.ionq.co/v0.3/jobs/{your-job-id}" \
    -H "Authorization: apiKey $IONQ_API_KEY"

This request will return the current status. Since we submitted to the simulator, our job is already completed! (Note: If you decided to submit to a QPU, you’ll have to wait for your job to work its way through the queue):

{
    "id": "7135ca98-176f-48c9-8616-8f53ec505028",
    "submitted_by": "65e8b97c521dcf001299126b",
    "name": "Hello many worlds!",
    "status": "completed",
    "target": "simulator",
    "qubits": 3,
    "circuits": 1,
    "results_url": "/v0.3/jobs/7135ca98-176f-48c9-8616-8f53ec505028/results",
    "gate_counts": {
        "1q": 1,
        "2q": 2
    },
    "cost_usd": 0,
    "project_id": "428499cb-c392-4ab1-ad8e-c954a1a99ff5",
    "request": 1718302151,
    "start": 1718302154,
    "response": 1718302154,
    "execution_time": 78,
    "predicted_execution_time": 8,
    "shots": 1024,
    "noise": {
        "seed": 917721158,
        "model": "aria-1"
    },
    "error_mitigation": {
        "debias": false
    },
    "children": []
}

​

Retrieving the results

Now that the job has completed, we can retrieve the results using the URL provided in the output:

curl "https://api.ionq.co/v0.3/jobs/{your-job-id}/results" \
    -H "Authorization: apiKey $IONQ_API_KEY"

Which will return a dictionary with the results of the job:

{
    "0": 0.4619140625,
    "1": 0.017578125,
    "2": 0.0185546875,
    "3": 0.0244140625,
    "4": 0.0185546875,
    "5": 0.025390625,
    "6": 0.0107421875,
    "7": 0.4228515625
}

The results request contains the histogram output of the probabilities of each measured state across all 1024 shots. Two things to note here: the output is sparse, that is, it only shows data for outcomes that were actually measured, and the output keys are formatted as big-endian integers, i.e. 0 is 000, 2 is 010, 3 is 011, and so-on, where the leftmost bit is the qubit with index zero from our submitted program.

​

Additional Resources

If you’re working on your own tools to interact with the API, the full API Reference has details on HTTP verbs and endpoints, expected response formats, and other features not covered in this guide.

Additionally, our best practices page provides detailed instructions for getting the most out of our trapped-ion systems, and our support center is always available to help you solve any problems you might run into.