Instances

Access to IBM Quantum™ Platform services is controlled by the instances (previously called providers) to which you are assigned. An instance is defined by a hierarchical organization of hub, group, and project. A hub is the top level of a given hierarchy (organization) and contains within it one or more groups. These groups are in turn populated with projects. The combination of hub/group/project is called an instance. Users can belong to more than one instance at any given time.

The hub/group/project hierarchy that makes up an IBM Quantum instance.

Users with a public account automatically belong to the ibm-q/open/main Open Plan. For organizations outside of IBM®, designated hub or group administrators assign users to instances.

To see the instances to which you have access, look at the bottom of your Account page.

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 QPU allocated to the plan fairly, an individual can have no more than three jobs running and/or in the queue (across all QPUs) 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.

View your instances

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

List your instances programmatically

You can view a list of your instances on your account settings page, or you can use the instances() method.

View instances in the IBM Quantum interface

Within the IBM Quantum interface, the IBM Quantum Platform dashboard, Compute resources, and Jobs pages display information such as usage metrics, jobs, and QPUs based on your instance. If you have access to multiple instances, use the dropdown in the menu bar to switch between instances.

If you switch to a different instance, it is remembered the next time you log on and, assuming that it's still a valid instance, information pertaining to that instance is displayed. By default, the first premium instance you have access to is used. If you do not have any premium instances, the first open instance is shown.

How jobs relate to instances

When you execute a task using an IBM Quantum service (for example, sending circuits to a QPU), a job instance is returned to you. Regardless of which service is being used, a job can track the progress of the submission through IBM Quantum, and retrieve the final computation results. Because services are coupled to instances, the jobs created from these services are also tied to the specific instance being used. Therefore, if a user is removed from an instance, their jobs and the associated results are no longer accessible.

How usage affects job priority within an instance

This section applies to Premium Plan users only, since their access includes multiple instances. 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 that has already run many jobs might have a lower priority when compared to an instance that has very low usage, depending on allocation.

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 (use the instance switcher at the top of the page to change which instance is reflected on your dashboard).

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.

Collaborator's dashboard view, reflecting an instance that has exceeded its specified limit

Collaborator's dashboard view, reflecting an instance (with no limit specified) that has exceeded its allocation

Specify an instance in your code

You can specify an instance when initializing the service or when choosing a QPU. You can copy the service-level code by clicking the three dots by the instance name on the Instances section of the Account overview page.

 
# Optional: List all the instances you can access.
service = QiskitRuntimeService(channel='ibm_quantum')
print(service.instances())
 
# Optional: Specify it at service level. This becomes the default unless overwritten.
service = QiskitRuntimeService(channel='ibm_quantum', instance="hub1/group1/project1")
backend1 = service.backend("ibmq_manila")
 
# Optional: Specify it at the backend level, which overwrites the service-level specification when this backend is used.
backend2 = service.backend("ibmq_manila", instance="hub2/group2/project2")
 
sampler1 = SamplerV2(mode=backend1)    # this will use hub1/group1/project1
sampler2 = SamplerV2(mode=backend2)    # this will use hub2/group2/project2

Leave an instance

To leave an instance, visit the instance list on your Account page. Select the instance you wish to leave, then select the overflow menu and choose Leave instance.

Next steps