::: AQT JSON Tutorial

AQT supports direct calls to the API in a JSON data format. This allows the execution of quantum circuits without the need to install a full quantum software development kit, like Qiskit or Cirq.


For accessing the AQT API directly, the requests package needs to be installed by using the pip tool on the command line:

pip install requests

Use your AQT credentials

After installation we can import the put method by the following Python code:

from requests import put

Next we need to set up some variables:

access_token = 'MY_TOKEN'
header = {'Ocp-Apim-Subscription-Key': access_token}
repetitions = 100
num_qubits = 2

Where BACKEND_URL is the URL of the AQT backend API and MY_TOKEN is your access token for a specific AQT device. You need to subscribe to an AQT backend at the AQT Gateway Portal and retreive the corresponding URL and token.

Sample a quantum circuit

The quantum circuit needs to be described in a JSON format. Here we prepare the Bell state \( \ket{\psi}=\frac{1}{\sqrt{2}}(\ket{00}-\mathrm{i}\ket{11}) \) by executing a Mølmer–Sørensen gate on two qubits and store it in json_str. The put method sends the request to the AQT API.

json_str = '[["MS", 0.5, [0,1]]]'
data = put(url,
           data={'data': json_str,
                 'access_token': access_token,
                 'repetitions': repetitions,
                 'no_qubits': num_qubits,
                 'label': 'custom'},

To retreive the results we query the API with data['id'], which was returned with the previous call, and repeat until data['status'] is set to 'finished'.

id_str = data['id']
while True:
    data = put(url,
               data={'id': id_str,
                     'access_token': access_token},
    if 'status' not in data.keys():
        raise RuntimeError(
                'Got unexpected return data from AQT server: \n' +
    if data['status'] == 'finished':
    elif data['status'] == 'error':
        raise RuntimeError(
                'Got unexpected return data from AQT server: \n' +

The results from executing the quantum circuit are stored in data['samples']. This list of return values will be about 50% 0, i.e. both qubits measured to be zero, and about 50% 3, i.e. both qubits measured to be one.

AQT Simulators

The AQT simulators are capable of running ideal simulations (without a noise model) and real simulations (with a noise model) of a quantum circuit. Using a simulator with noise model allows you to estimate the performance of running a circuit on the real hardware. Switching between the two simulation types is done by using the respective BACKEND_URL in above example.

For running a simulation without noise model use

url = 'https://gateway.aqt.eu/marmot/sim/'

whereas for a simulation with noise model use

url = 'https://gateway.aqt.eu/marmot/sim/noise-model-1'

We will provide different noise models in the future, which will be listed on the subscriptions page at the AQT Gateway Portal.

::: AQT JSON Syntax

General AQT JSON example

Generally speaking, the AQT JSON syntax is a series of quantum gates, i.e.

[gate_0, gate_1, ...]

where each gate is defined as

["gate_type", pulse_area, [qubits]]
  • gate_type has to be from the list of supported gates
  • pulse_area is the pulse area in units of \(\pi\)
  • qubits is a comma-separated list of qubits addressed by the gate.

Here is an example of a JSON string for two concatenated gates with a \( \pi/2 \)-pulse around the x-axis on the first qubit, then a \( \pi \)-pulse around the y-axis on the fifth qubit:

[["X", 0.5, [0]], ["Y", 1.0, [4]]]

See AQT Quantum Gate Definitions for a full list of basis gates supported by the AQT backends.

The result will be returned in the results field of the returned JSON string. For each repetition, an \(N\)-bit integer is listed, where \(N\) is the number of qubits in the circuit.

Remarks on the AQT Backend API

  • The circuit do be evaluated by the AQT backend is encoded as a JSON string.
  • Together with additional settings, like the number of repetitions and the number of qubits in the circuit, the JSON string is sent to the backend via the AQT API.
  • To access the backend, its URL and access token are required. Both can be obtained on the AQT Gateway Portal.
  • In above example, the requests.put() method within Python is used for sending the request, but other means to send the required JSON string should work likewise.