Submit a Quantum Circuit to Real Hardware With Your Own API Key

Who this page is for

You already have an account with a quantum hardware provider, you have a circuit written as OpenQASM, and you want one place to submit jobs and read results without juggling several SDKs. This page explains the general shape of hardware submission first, because it is different from running a simulator, and then describes precisely what Q-Bridge does with the key you give it. If you have not run a circuit anywhere yet, the companion page on the online OpenQASM simulator covers the simulation side.

Submission is asynchronous

Running a circuit on a simulator is a function call: send the text, wait a moment, get counts back. Running it on a real device is a request to a shared machine owned by someone else. The provider receives your circuit, checks it against the device, and places it in a queue behind other people's jobs. The device may also be in calibration or offline. So the honest answer to "when will I get my result" is "later", and the only way to know is to ask the provider for the job's status.

This changes how a client has to behave. It cannot block waiting for counts. It has to submit, receive a job identifier from the provider, remember it, and check back. Every serious hardware workflow, whether it is a notebook, a script or a web dashboard, ends up with that same loop: submit, hold a handle, poll, retrieve.

Devices are not interchangeable

A simulator will run any valid circuit up to its memory limit. A device will not. Each device has a fixed number of physical qubits, a native gate set, and a connectivity map that says which pairs of qubits can interact directly. A circuit written with arbitrary two-qubit gates between arbitrary qubits has to be rewritten into that device's native gates and routed onto its connectivity before it can run. Providers do this translation on their side when you submit, and the result can be a deeper circuit than the one you wrote.

The practical consequence is that the same OpenQASM file may be accepted by one device, rejected by another for exceeding its qubit count, and run with very different noise on a third. Before you submit, it is worth knowing the device's qubit count and gate set, which the provider publishes, and the depth and two-qubit gate count of your own circuit. The Q-Bridge circuit analyzer reports gate count, depth, qubit count and the interacting qubit pairs from the text, which is enough to see whether a circuit is plausible for a device before you spend queue time on it.

Why the key is the sensitive part

Your provider key is not like a login to a free website. On most providers it is tied to a billing relationship, a usage quota, or an allocation of device time. Anyone who holds the key can submit jobs as you, consume your allocation and read your results. That makes the key the single most sensitive thing in the whole workflow, more sensitive than the circuit itself.

So the right questions to ask of any tool that offers to submit on your behalf are concrete ones. Where does the key live while I use the tool? Is it written to disk or to browser storage? Is it sent to the tool's own server, and if so, is it stored there? Which requests carry it? Who else could read it? A tool that cannot answer those questions precisely should not be trusted with the key.

How Q-Bridge handles bring-your-own credentials

Q-Bridge is built around a simple rule: the service holds no hardware-vendor credentials. Real hardware is bring-your-own credentials on every plan. Here is what that means in the live web app, stated so you can check it against your own expectations.

You enter a key in the dashboard under Settings, on the Vendor Credentials page. The key is kept in the memory of the current browser tab. It is not written to browser storage of any kind. Moving between dashboard pages keeps it; a full page reload, closing the tab or logging out drops it, and you type it again. That is a deliberate trade-off: re-entering a key after a reload is cheap, and a key persisted in plaintext is not.

The key is attached to exactly three kinds of request: submitting a job to a non-simulator backend, fetching that job's result, and fetching the backend catalogue. It is not attached to anything else, and the web app's own server-side proxy strips the header from any other route. A simulator job never carries the key at all.

On the backend list, the built-in simulator is always first. Other backends come from the service's catalogue, and each one is marked usable only when the service can actually reach that provider with the credentials you supplied. If no key is present, those backends are listed but not usable. The catalogue does not invent numbers it did not receive.

What happens after you press submit

With a key present and a hardware backend selected, the job form posts your circuit, shot count and backend to the service. The service forwards the circuit to the provider using the credentials from that one request, records the provider job id and the provider's reported state on your job, and leaves the job in the running state, because the provider's queue is asynchronous. The credentials are used for that request and are not persisted on the server.

When you open the job's result page with the key still present in your tab, the web app sends the key along with the result request. The service asks the provider for the live state of the job. If the provider has finished and returned measurement counts, those counts are stored and shown as a histogram, the same way simulator results are shown. If the provider reports completion but counts cannot be retrieved, the job is marked result unavailable with a reason. No hardware counts are invented at any point.

If you submit to a hardware backend without a key, the job does not hang and it does not quietly fall back to simulation under a hardware label. It ends as failed, with a message telling you to add a provider credential in Settings or to choose the simulator backend.

What Q-Bridge does not do

It does not hold, broker or resell device time. It does not publish device benchmarks, queue estimates or fidelity figures, and it does not promise that any particular device is available to you; that depends on your provider account. It does not run noise-aware simulation, and its built-in simulator is an ideal statevector simulator with no noise model, so a simulator result is a reference answer rather than a prediction of device behaviour. It does not perform your billing with the provider. What you pay for device time, and whether a device accepts your job, is a matter between you and your provider.

A sensible way to work

Write the circuit in the browser editor and run it on the built-in simulator first. That tells you the ideal distribution for free and catches syntax errors before they cost queue time. Run the analyzer to see the depth, the two-qubit gate count and which qubit pairs interact, and compare that to the device you have in mind. Then enter your provider key in Settings, pick the hardware backend from the list, submit, and come back to the job page later with the key still present to pull the result. When you are done, log out or close the tab, and the key is gone from Q-Bridge.

The dashboard requires an account; a Free plan exists and the simulator qubit limits per plan are listed on the pricing page. You can create an account to start with the simulator and add your own provider key when you are ready for hardware.