Initialize your Qiskit Runtime service account

Before using Qiskit Runtime, you have to initialize (instantiate) your account by submitting (loading) credentials. These credentials can be manually submitted each time you initialize the Qiskit Runtime service, or you can save them for reuse.

Notes

If you are using a public computer or other untrusted environment, follow the instructions in Initialize the service in an untrusted environment instead.
Follow these instructions if you want to connect by using the REST API instead of using Qiskit.
If necessary, use this information to configure your firewall to enable access to the IBM Quantum API endpoints.

Before you begin

Ensure that you have completed these steps:

Ensure that you are a member of an IBM Cloud account. See Set up your IBM Cloud account for instructions.
Create (or have access to) at least one instance. Follow these steps to verify:
1. Log in to IBM Quantum Platform.
2. Make sure that the correct account and region are selected in the account switcher in the header.
3. If you have one or more instances shown, you're done with this step. Otherwise, create an instance.
Ensure you are working in an active Python environment with the Qiskit SDK and Qiskit Runtime installed.
Activate the Python virtual environment and run Python in your virtual environment.

Find your access credentials

Find your API key (also referred to as an API token). From the dashboard, create your API key, then copy it to a secure location so you can use it for authentication. The token will not be visible again. Note that you can use a single API key to connect to any region.
Optional: Find the instance you want to use from the Instances page. Hover over its CRN, click the icon to copy it, then save it in a secure location so you can use it to identify the instance.

Connect Qiskit with your Qiskit Runtime service instance

Note

These instructions are designed for qiskit_ibm_runtime v0.42 or later. Some features are not enabled in earlier versions of qiskit_ibm_runtime. In these cases, you should always provide a value for channel, token, and instance, either explicitly or through a saved account.

The basic code to connect Qiskit with your Qiskit Runtime service instance follows. However, there are several different ways to customize the QiskitRuntimeService options, depending on your needs. These options are described in the following sections.

from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(channel=<channel>,
            token=<your-API_KEY>, # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard
            instance=<instance_CRN>)

Note

The default channel is ibm_quantum_platform. Because this is almost always the appropriate channel, it is not included in the examples.

Quick start path: Specify credentials explicitly

The fastest way to get a QiskitRuntimeService instance running is the direct instantiation method: explicitly provide the API token (key) and CRN (instance identifier) every time you need to initialize the Qiskit Runtime service. See Find your access credentials if necessary.

from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(token=<cloud_api_key>, # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard
            instance=<instance_CRN>)

This path is reliable but can be tedious if you need to load the same details repeatedly. To avoid loading your credentials multiple times, if you are working in a trusted Python environment (such as on a personal laptop or workstation), you can use saved account credentials, as described in the following section.

Although the instance input parameter is optional, it is recommended that you always provide this information, unless you want to use a single service to work with several instances. In this situation, see the automatic instance selection section.

Quick start path: Specify saved credentials

If you have already saved your credentials, use the following code to apply your default credentials. For instructions to save credentials, see Save your access credentials.

from qiskit_ibm_runtime import QiskitRuntimeService
 
# run every time you need the service
service = QiskitRuntimeService()
...

If you named one or more sets of credentials - for example, for open and premium access - use the following code to use a set of named credentials.

from qiskit_ibm_runtime import QiskitRuntimeService
 
# run every time you need the service
service = QiskitRuntimeService(name="<name_of_saved_credentials>")
...

Considerations when loading saved credentials

If you initialize a service with token and name, the token is ignored and the saved details from the name account are loaded.

In the following example, the service loads the details from account_A and does not use token_B:
```
from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(token="token_B", name="account_A")
```
If you provide a name and an instance when initializing a service, the service tries to load the name account and connect to the specified instance. If there is any conflict, a warning is raised.

In the following example, the service tries to load the credentials for account_A and use instance CRN_B - even if there is a different instance specified in account_A:
```
from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(instance="CRN_B", name="account_A")
```
The service tries to load the default saved account only if you don't provide a token or name when initializing a service. However, if an instance is provided explicitly, the service tries to connect to that instance by using the default credentials. If there is any conflict, a warning is raised.

In the following example, the service tries to load the default credentials and use the instance CRN_B - even if there is a different instance specified in the default account:
```
from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(instance="CRN_B")
```
If you save multiple sets of credentials but don't specify one when initializing the service and there is no default saved account, the one whose name comes last alphabetically is used.

In the following example, the user saved accounts named "my_premium" and "my_open" but didn't mark either as the dfault. They then initialized the service by using the following code. In this case, the "my_premium" credentials are used:
```
from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService()
```

Automatically select the instance

If you provide a token but don't provide an instance CRN when instantiating the service, QiskitRuntimeService authenticates to the account identified by the token and uses automatic instance selection to choose the most relevant instance for the requested task. If you have several instances available within your account, the service automatically chooses from the available instances, depending on the resource requested and these QiskitRuntimeService options (if set): plans_preference, region, tags.

plans_preference: The types of instance plans to prioritize. For example, if [open] is passed in, only Open Plan instances are available. Accepted values are open, premium, pay-as-you-go, flex, and on-prem. If plans_preference is not specified, free plans are prioritized over paid plans.
region: The instance region. Accepted values are us-east and eu-de.
tags: The instance tags. Accepts a list of tag name strings.

Note

You can set up your saved credentials to automatically select an instance.

The instance is found and used in this order:

If your account only has access to one instance, it is selected by default.
If saved credentials are being used and an instance was specified with the credentials, that instance is used. See Considerations when loading saved credentials.
If your account has multiple instances that can access the requested QPU, the system uses your specified plan preferences to choose a plan and instance. For Qiskit Runtime v0.42 and later, free plans are prioritized by default.
If your account has access to multiple instances but only one can access the requested QPU, the instance with access is selected. If this instance is not associated with a free plan, a cost will be incurred.

Examples

In this example, the service searches all instances that are available to the account to find ones that can access the specified backend:

service = QiskitRuntimeService(token=<your-API_KEY>)

In this example, the service searches all instances that are available to the account in the EU region to find ones that can access the specified backend:

service = QiskitRuntimeService(token=<your-API_KEY>, region="eu-de")

In this example, the service searches all instances that are available to the account and are tagged as services to find ones that can access the specified backend:

service = QiskitRuntimeService(token=<your-API_KEY>, tags=['services'])

In this example, the service searches all premium and open instances that are available to the account to find ones that can access the specified backend. If a backend is in both a Premium and an Open Plan instance, the Premium Plan instance is prioritized because premium is specified first in plans_preference.

service = QiskitRuntimeService(token=<your-API_KEY>, plans_preference=['premium', 'open'])

Determine which instance was chosen

The selected instance is returned as a warning. Additionally, you can run service.active_instance() to determine the active instance.

Local testing with Qiskit Runtime

The QiskitRuntimeService class can be initialized with channel=local to perform local simulation. In this case, authentication is not required and there is no need to provide values for token or instance. Therefore, it is not recommended that you save a local account. Instead, you can do direct instantiation:

from qiskit_ibm_runtime import QiskitRuntimeService
 
# Initialize for local testing
 
service QiskitRuntimeService(channel="local")

Next steps

Recommendations

Create and manage instances.
Initialize the service in an untrusted environment.
Set up to use IBM Quantum Platform with REST API.
Follow the steps in Hello world to write and run a quantum program.