Run circuits on IonQ’s quantum hardware

IonQ is a leading quantum hardware startup, developing general-purpose trapped ion quantum computers and accompanying software to generate, optimize, and execute quantum circuits. In this guide we will upgrade your IonQ account to a paid tier, prepare our IonQ project, confirm our QPU access, estimate our IonQ spend, send our quantum circuit to IonQ’s quantum hardware, and ultimately retrieve our quantum circuit’s results asynchronously. In order to follow along, it is essential that you have completed our previous guides for installing Python via UV (which also covers operating a shell command-line interface), and setting up an IonQ project. For additional information on IonQ’s SDK, see IonQ’s Qiskit tutorial.

1. Upgrade your IonQ account

It’s important to understand that the use of real quantum hardware (versus simulated quantum hardware) is inherently expensive. Completing this tutorial will require you to purchase compute power from IonQ.

In our previous IonQ guide we have created an IonQ account, generated an IonQ API key, and put it to use running a quantum circuit on IonQ’s quantum simulator. Fantastic. But this is as far as we can go using IonQ’s free account tier. In order to run our quantum circuit on actual IonQ hardware, you must upgrade to a paid IonQ account.

If you’ve submitted a Qollab RFP and have been approved for a grant, your IonQ account will include a generous number of credits that can be used towards a compute spend. If you do not have available IonQ credits, visit the “Backends” page of your IonQ account, select a QPU that you would like to use, and click its “Out of Plan, Request Access” badge. Follow the prompts to request access and join a paid account tier. Additionally, you have the option to email support@ionq.com or fill out this support form to discuss account options.

This first step in our guide to running circuits on IonQ’s quantum hardware will take some time because it requires dialogue with real human beings. Be patient. Good things will come.

2. Prepare our IonQ project

In our previous IonQ guide we created a new project, installed IonQ’s SDK, updated our transpile settings, and safely included our IonQ API key inside our project. If you skipped these steps, now is the perfect time to tend to them as we will build off of their output here. You will also need to generate an IonQ API key if you have not done so already. Once you have upgraded your IonQ account to a paid tier (see above) and prepared your IonQ Python project (as described in our previous guide), you will be ready to proceed to the next step.

3. Confirm your IonQ QPU access

Your IonQ account has been upgraded, and your local Python project is setup for action. Let’s confirm what IonQ hardware your API key can access. Point your Web browser to the “Backends” page of your IonQ account.

4. Prepare our quantum circuit

Create a new blank file within your project folder, name it ionq-hardware-submit.py, open it with your source code editor, and paste the following code into it. It should look very similar to our ionq-simulator.py code from our previous tutorial. Some differences have been highlighted here:

from qiskit import QuantumCircuit
from qiskit_ionq import IonQProvider, ErrorMitigation
qc = QuantumCircuit( 2, name="Bell state on IonQ QPU" )
qc.h( 0 )
qc.cx( 0, 1 )
qc.measure_all()

provider = IonQProvider()
backend = provider.get_backend( "qpu.aria-1" )
job = backend.run( 
    qc, 
    shots=1000,
    error_mitigation=ErrorMitigation.NO_DEBIASING)
print( "Submitted job:", job.job_id() )print( "Status:", job.status() )

Be certain to swap out the QPU id in the example above for the id of a QPU that you have access to. For example, our code above calls upon the qpu.aria-1 QPU, but perhaps you are using qpu.forte-1, etc.

5. Estimate your IonQ spend

How much credit might you need for experimenting? IonQ’s Resource Estimator enables you to predict your potential spend ahead of time according to your circuit’s number of qubit registers, gates, and so on. Our simple Bell state circuit above, run for one thousand shots, one single time, on IonQ’s “Aria” device without error mitigation, would cost just a bit above USD 12 at current early 2026 rates. But the same setup run on IonQ’s “Forte” architecture with error mitigation enabled would cost nearly USD 170. (You’ll find that the cost of error mitigation is relatively higher for small to medium circuits, and relatively lower for large circuits.) Always use the IonQ’s Resource Estimator beforehand to reduce unwanted surprises.

A note on error mitigation

IonQ enables error mitigation be default. In our ionq-hardware-submit.py script above, we purposely disable error mitigation. Why would we do this? Because error mitigation is rather expensive and we don’t need it in order to demonstrate how to send jobs to IonQ’s QPUs. However, it’s likely that you will want to enable error mitigation on future jobs in order to obtain the most useful results from real quantum hardware. (What is IonQ’s quantum error mitigation, and how does it work? Read IonQ’s guide to debiasing for more information.) Experiment with IonQ’s Resource Estimator and use your own judgement regarding when to employ error mitigation for your own circuits.

6. Submit your circuit to IonQ’s quantum hardware queue

It’s time. Everything has led up to this moment of executing your quantum circuit on real quantum hardware. Enter the following into our shell:

set -a;
source ./.env; 
set +a; 
uv run python ionq-hardware-submit.py

Our shell will respond with a job id. This is your ticket to read the results of your real quantum operation once those results are ready.

Patience, please

While simulator results arrive near-instantly (at least for simple circuits), hardware jobs are queued, processed in order of their queue index, and take some time to resolve. To get an overview of current IonQ QPU job queue times, visit your account’s Backend page.

7. Retrieve IonQ circuit results asynchronously

Once we’ve submitted a job to one of IonQ’s QPUs, we can check on that job’s status using the “My Jobs” tab of your account page.

You can also programmatically poll the status of a job using a script similar to the following. Create a new file within your project’s folder and name it ionq-hardware-results.py. Copy the following code into your file, replacing “PASTE_JOB_ID_HERE” with your real job’s id.

from qiskit_ionq import IonQProvider

provider = IonQProvider()
backend  = provider.get_backend( "qpu.aria-1" )
job = backend.retrieve_job( "PASTE_JOB_ID_HERE" )
print( job.status() )
print( job.get_counts() )

Enter the following into your shell, from within your project’s folder:

set -a; 
source ./.env; 
set +a; 
uv run python ionq-hardware-results.py

Celebrate

Have you received your hardware results yet? Yes? Well then you’ve accomplished a lot here: You’ve just harnessed the power of our quantum universe to compute a thousand entangled coin flips. Take a beat, savor the moment. More Qollab tutorials are on on the way. In the meantime check out IBM’s incredibly informative Qiskit YouTube channel.