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 (such as 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 Cloud Resource Name (CRN). This CRN is used when sending workloads from your Qiskit programs.

The IBM Quantum Platform dashboard displays the instances to which you have access. You can view full details, edit, and delete instances on the Instances page.

It is important that you understand which instance you are using, because all instances that are not associated with the Open Plan incur a cost.

Open Plan instance

By default, users who sign up for an IBM Quantum account are assigned to the Open Plan and the Open Plan's instance, ibm-q/open/main. To guarantee that everyone can use the quantum computers allocated to the plan fairly, an individual can have no more than three jobs running and/or in the queue (across all quantum computers) at the same time. Submitting more than three jobs at a time will return error #3458, and additional jobs will be canceled.

Those using the Open Plan instance have up to 10 minutes total of quantum time per month, which resets at 00:00:00 UTC on the first of each calendar month. Open Plan users can track their usage on the Platform dashboard, Workloads, and Account pages.

Standard Plan instance

By default, users who sign up for an IBM Quantum account are assigned to the Standard Plan, which is a paid plan. To use this plan, you must create an instance and assign it to the plan. All workloads sent to QPUs by using this plan incur a charge.

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 view an instance's usage on the Instances page, or, for those with the proper authority, the Analytics page. Note that the pages might show different usage numbers because the Instance page shows usage in a 28-day rolling window prior to the current timestamp, while the Analytics page uses full-day boundaries.

If an instance has been marked as "limited" by your administrator (you will see a "Remaining" column in the usage area) and the instance exceeds its allocation (defined by your administrator) within the 28-day rolling window, any active workload will continue running (including sessions) but pending workloads will remain in the queue until more time is available. 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.

An alert displays on an instance's usage when it has exceeded its allocation.

Specify an instance in your code

You must use the CRN to specify an instance to use; either when initializing the service or when sending the workload to a QPU. The instance's CRN is listed on the Platform dashboard. Before running the below code, follow the steps to save an account.

# Specify an instance at service level. This becomes the default unless overwritten.
service = QiskitRuntimeService(instance="<CRN>")
backend = service.backend("<QPU-name>")

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:

   • Which QPUs are available.
   • Where the jobs' classical computation, such as compilation, takes place.
   • Where the user's workflow data remains.

   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. If this instance is not associated with a free plan, a cost will be incurred when this instance is used to run workloads.

5. 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.

6. 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.

7. 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.

8. 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. Click the overflow menu at the end the instance's row, and select Edit details.

Next steps