Skip to main contentIBM Quantum Documentation Preview
This is a preview build of IBM Quantum® documentation. Refer to quantum.cloud.ibm.com/docs for the official documentation.

Initialize your Qiskit Runtime service account

Before using Qiskit Runtime, you have to initialize your account by submitting credentials. These credentials can be submitted each time you run a job, or you can save them for reuse.

Before you begin

Ensure that you have completed these steps:

  1. Ensure that you are a member of an IBM Cloud account set up your own IBM Cloud account.

    Notes
    • To avoid adding your credit card information, you can set up a 30-day trial account and optionally upgrade it later.
    • You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the IBM Quantum Platform interface.
    • If you are invited to join an IBM Cloud account, you will get an email invitation to join the account. Follow the instructions in that email.

  2. Create (or have access to) at least one instance.

    1. Log in to IBM Quantum Platform with an IBMid or Google account. If you don't have one, you are guided through creating one.

    2. Make sure that the correct account and region are selected in the account switcher in the header, as shown in the following image.

      The region controls where your jobs are run and where the job data is kept. You can access either region by using the same API key, but you can only see and access the instances that were created in the region that you're logged in to.

      The IBM Quantum Platform header is shown. The account switcher is to the right of the search bar. The region switcher is to the right of the account switcher.
      IBM Quantum Platform header

    3. Go to the IBM Quantum Platform dashboard. If you have one or more instances shown, you're done with this step. Otherwise, create an instance.

  3. Ensure you are working in an active Python environment with the Qiskit SDK and Qiskit Runtime installed.

  4. Activate the Python virtual environment and run Python in your virtual environment.

Find your access credentials

  1. 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, so make sure it's copied somewhere. Note that you can use a single API key to connect to any region.
  2. Optional: Find the instance you want to use from the Instances page. Click the icon to copy its CRN, then save it in a secure location so you can use it to identify the instance.

Connect Qiskit with your service instance

Note

This guide is designed for qiskit_ibm_runtime v0.42 or later. If you are using an earlier version of qiskit_ibm_runtime, certain features will not be enabled. In these cases, we recommend always providing 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=<cloud_api_key>, instance=<instance_CRN>)

Quick start path: Specify credentials explicitly

The fastest way to get a QiskitRuntimeService running is direct instantiation method: explicitly providing the API token (key) and CRN (instance identifier). See Find your access credentials section if necessary.

from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService(token=<cloud_api_key>, 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

You can use the following snippet as a quick start reference as long as you instantiate the service precisely as indicated in this example. For more info on the mechanisms used to save and load accounts, and possible variations from this example, see section C:

Automatically select the instance

Use the information in this section if you want Qiskit Runtime to automatically select the instance.

If you provide a token but don't provide an instance CRN when instantiating the service, the QiskitRuntimeService authenticates to the account identified by the token and relies on 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 switches between 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.

region: Specify the instance region. Accepted values are us-east and eu-de.

tags: Specify the instance tags. Accepts a list of tag name strings.

Next steps

Recommendations