1# IonQ API Service
2
3IonQ's API provides a way to execute quantum circuits on IonQ's trapped ion quantum computers
4or on cloud based simulators.  As of April 2021 this access is restricted to partners.
5See [Access and Authentication](access.md) for details of access.
6
7## Service class
8
9The main entrance for accessing IonQ's API are instances of the `cirq.ionq.Service` class.
10These objects need to be initialized with an api key, see
11[Access and Authentication](access.md) for details.
12
13The basic flow of running a quantum circuit in a blocking manner is
141. Create a circuit to run.
151. Create a `cirq.ionq.Service` with proper authentication and endpoints.
163. Submit this circuit to run on the service and await the results of this call.
17(Or alternatively use asynchronous jobs and processing)
184. Transform the results in a form that is most useful for your analysis.
19
20Here is a simple example of this flow
21```python
22import cirq
23import cirq.ionq as ionq
24
25# A circuit that applies a square root of NOT and then a measurement.
26qubit = cirq.LineQubit(0)
27circuit = cirq.Circuit(
28    cirq.X(qubit)**0.5,            # Square root of NOT.
29    cirq.measure(qubit, key='x')   # Measurement store in key 'x'
30)
31
32# Create a ionq.Service object.
33# Replace API_KEY with your api key.
34# Or alternatively if you have the IONQ_API_KEY environment
35# variables set, you can omit specifying thee api_key parameters.
36service = ionq.Service(api_key=API_KEY)
37
38# Run a program against the service. This method will block execution
39# until the result is returned and periodically polls the IonQ API.
40result = service.run(circuit=circuit, repetitions=100, target='qpu')
41
42# The return object of run is a cirq.Result object.
43# From this object you can get a histogram of results.
44histogram = result.histogram(key='x')
45print(f'Histogram: {histogram}')
46
47# Or the data as a pandas frame.
48print(f'Data:\n{result.data}')
49```
50This produces output (will vary due to quantum randomness!)
51
52```
53Histogram: Counter({0: 53, 1: 47})
54Data:
55    x
560   0
571   0
582   0
593   0
604   0
61.. ..
6295  1
6396  1
6497  1
6598  1
6699  1
67
68[100 rows x 1 columns]
69```
70
71## Service options
72
73In addition to the `remote_host` and `api_key` there are some other options which are
74useful for configuring the service.  The most useful of these are
75
76* `default_target`: this is a string of either `simulator` or `qpu`. By setting this you
77do not have to specify a target every time you run a job using `run`, `create_job`
78or via the `sampler` interface.  A helpful pattern is to create two services with
79defaults for the simulator and for the QPU separately.
80
81* `max_retry_seconds`: The API will pull with exponential backoff for completed jobs.
82By specifying this you can change the number of seconds before this retry gives up.
83It is common to set this to a very small number when, for example, wanting to fail
84fast, or to be set very long for long running jobs.
85
86## Next steps
87
88[Learn how to build circuits for the API](circuits.md)
89
90[How to use the service API](jobs.md)
91
92[Get information about QPUs from IonQ calibrations](calibrations.md)
93