Create and manage instances

Access to IBM Quantum Platform services is controlled by the instances to which you are assigned. Users can belong to more than one instance at any given time.

An instance is a deployment of Qiskit Runtime. You need a different instance for every service plan (Open or Standard) you use in every region that you want to use. The account manager and anyone with enough permission can create an instance and define its configuration, such as its allocations, usage limits, quantum computers, and user permissions. Each instance is identified by a unique CRN. This CRN is used when sending workloads from your Qiskit programs.

Users with a public account can create an instance in the Open Plan. For organizations outside of IBM®, the organization's administrator assigns users to instances.

The IBM Quantum Platform dashboard displays the instances to which you have access.

Open Plan instance

After you have an IBM Cloud® account, you can create an instance in the Open Plan and access up to 10 minutes total of quantum time per 28-day rolling window.

View your instances

You can see information about your instances programmatically or in the user interface.

List your instances programmatically

You can use the instances() method to list your instances programmatically.

View instances on IBM Quantum Platform

The IBM Quantum Platform dashboard, Compute resources, and Workloads pages display information such as workloads and quantum computers based on your account. If you have access to multiple accounts, use the dropdown in the menu bar to switch between accounts.

By default, the Workloads and Compute resources pages display all data across all instances you can access within an account. You can filter the data table by a specific instance using the filter icon in the upper right.

How usage affects job priority within an instance

When determining which jobs to run, the fair-share scheduler takes into account an instance's usage compared to its allocation. For example, an instance with a large allocation that has already run many jobs, or has run one very long job, might have a lower priority when compared to an instance with a smaller allocation but very low usage.

The jobs you run and the jobs run by other collaborators in the same instance count toward the reported usage for that instance. You can see the usage for an instance on your dashboard.

If an instance has been marked as "limited" by your administrator and the instance exceeds its allocation (defined by your administrator) within the 28-day rolling window, active and pending workloads might be canceled. If an instance is not limited and the instance exceeds its allocation, jobs run with that instance are likely to run at a lower priority and experience longer queue times.

Specify an instance in your code

You can specify an instance when initializing the service or when choosing a quantum computer. You can copy the Cloud Resource Name (CRN) of an instance by clicking the copy button next to its CRN on the Platform dashboard.

 
# Optional: List all the instances you can access.
service = QiskitRuntimeService(channel='ibm_cloud')
print(service.instances())
 
# Optional: Specify it at service level. This becomes the default unless overwritten.
service = QiskitRuntimeService(channel='ibm_cloud', instance="CRN")
backend1 = service.backend("ibm_kyiv")
 
# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used.
backend2 = service.backend("ibm_kyiv", instance="CRN")
 
sampler1 = SamplerV2(mode=backend1)
sampler2 = SamplerV2(mode=backend2)

Add an instance

1. To add an instance to your account, first ensure you have the correct account and region selected in the account switcher in the top header.

   About regions

   The instance will be created in the selected region. This region determines these important characteristics:

   • The region determines which QPUs are available.
   • The jobs' classical computation, such as compilation, takes place in the region.
   • The user's workflow data remains in the region.

   The workflow data includes the input circuits, circuit parameters, and quantum computation results. It does not include metadata, such as number of shots, size of circuits, or other job statistics.

   To avoid exposure of the user's workflow data to a global Distributed Denial of Service protection layer, you can use Virtual Private Endpoints. qiskit-ibm-runtime supports this through the private_endpoint parameter.

2. From the dashboard Instances pane, click View all, or go to the Instances page from the main menu.

3. From the Instances page, click Create instance +. Enter a name and optionally add tags. If you have access to more than one resource group in IBM Cloud®, you can choose to change the resource group this instance belongs to. See Managing resource groups and Giving access to resources in resource groups for more information.

4. Select the plan this instance is associated with (for example, Premium Plan), then enter the number of minutes to allocate to this instance. The unallocated time available to use appears under the allocation entry box.

5. Click Next. A list of the QPUs the instance can access is shown. If you want the instance to have access to all the QPUs listed (and all QPUs added to this plan in the future), click Next. To customize which QPUs can be accessed with this instance, click the "Customize allocated compute resources" toggle. Select specific QPUs that this instance can access, then click Next.

   Note

   If you customize the allocated compute resources, the available QPUs will never be automatically updated, regardless of any changes made to the parent plan. However, you can manually add or remove QPUs later. If you do not customize them, you will always have access to any QPU the account has access on the plan. So if in the future there is a new system added to the plan, the instance automatically has access to it.

6. Click Create instance. You can now view the instance on the Instances page (if you have set up multiple plans on your account, each plan type has its own tab on the Instances table).

A "collaborators" access group is automatically created for this instance. Users added to this access group can use the time allocated to this instance. You can modify or create additional access groups by using the IBM Cloud console.

Edit an instance and its allocation

Find the instance on the Instances page. To edit the instance, click the overflow menu at the end the instance's row, and select Edit details. In the modal that opens, you can edit the name of the instance, the number of minutes allocated to the instance, and which compute resources the instance can access.

Delete an instance

Find the instance on the Instances page. To delete the instance, click the overflow menu at the end the instance's row, and select Delete.

Next steps