---
title: QiskitRuntimeService (latest version)
description: API reference for qiskit_ibm_runtime.QiskitRuntimeService in the latest version of qiskit-ibm-runtime
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime/qiskit-runtime-service
---

# QiskitRuntimeService

*class* `QiskitRuntimeService(*args, **kwargs)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L59-L1419)

Bases: `object`

Class for interacting with the Qiskit Runtime service.

Recommended uses:

- Direct instantiation:

  > ```python
  > from qiskit_ibm_runtime import QiskitRuntimeService
  >
  > service = QiskitRuntimeService(
  >     channel="ibm_quantum_platform", # optional
  >     token="API_KEY",
  >     instance="CRN" # recommended
  >     )
  > ```

- Saving default acccount:

  > ```python
  > from qiskit_ibm_runtime import QiskitRuntimeService
  >
  > QiskitRuntimeService.save_account(
  >     token="API_KEY",
  >     instance="CRN",
  >     set_as_default = True
  >     )
  >
  > service = QiskitRuntimeService()
  > ```

The minimum required information for service authentication to a non-local channel is the `token`. The `local` channel doesn’t require authentication. For non-local channels, it is recommended to always provide the relevant `instance` to minimize API calls. If an `instance` is not defined, the service will fetch all instances accessible within the account, filtered by `region`, `plans_preference`, and `tags`. If `plans_preference` is not set, free and trial instances will be prioritized over paid instances.

When using multiple instances, [`QiskitRuntimeService`](#qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService") will internally manage which instance is active at a given time. Methods such as [`backend()`](#qiskit_ibm_runtime.QiskitRuntimeService.backend "qiskit_ibm_runtime.QiskitRuntimeService.backend"), [`backends()`](#qiskit_ibm_runtime.QiskitRuntimeService.backends "qiskit_ibm_runtime.QiskitRuntimeService.backends"), [`job()`](#qiskit_ibm_runtime.QiskitRuntimeService.job "qiskit_ibm_runtime.QiskitRuntimeService.job") and [`jobs()`](#qiskit_ibm_runtime.QiskitRuntimeService.jobs "qiskit_ibm_runtime.QiskitRuntimeService.jobs") can result in changing the active instance. It is recommended to use the [`active_instance()`](#qiskit_ibm_runtime.QiskitRuntimeService.active_instance "qiskit_ibm_runtime.QiskitRuntimeService.active_instance") method for checking which instance is active, or use a separate [`QiskitRuntimeService`](#qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService") object per instance for more fine-grained control.

Also note that only one account per API token can be used. The API token is linked to the account it was created in. If you want to use multiple accounts, you must create multiple API tokens.

The service will attempt to load an account from file if (a) no explicit `token` was provided during instantiation or (b) a `name` is specified, even if an explicit `token` was provided to the service constructor. The account will be selected based on the following criteria:

- **If a `filename` is specified, account details will be loaded from `filename`,**

  else they will be loaded from the default configuration file.

- **If a `name` is specified, the corresponding account details will be loaded from**

  the configuration file, including `channel`, `token`, `instance`, `region`, `plans_preference`, and the advanced configuration parameters: `url`, `url_resolver`, `private_endpoint`, `verify`, and `proxies`. **Important Note**: An explicit `instance` value provided during instantiation will **overwrite** the value of the loaded `instance`.

- **If no `name` is specified: if `channel` is specified, the service will load the**

  default account associated with that channel from the configuration file. Else, it will fall back to the overall default account, defined when calling [`save_account()`](#qiskit_ibm_runtime.QiskitRuntimeService.save_account "qiskit_ibm_runtime.QiskitRuntimeService.save_account") with `set_as_default=True`.

**Parameters**

- **channel** – String that identifies the service platform. This is set to `ibm_quantum_platform` by default, but can additionally take `local` and `ibm_cloud` as values. `ibm_cloud` is a legacy option and points to the same path as `ibm_quantum_platform`, the recommended value is ibm\_quantum\_platform\`. If `local` is selected, the local testing mode will be used, and primitive queries will run on a local simulator. For more details, check the [Qiskit Runtime local testing mode](/docs/guides/local-testing-mode) documentation. For non-local modes, the channel is used to resolve the default API URL value. `ibm_cloud` was the identifier for the legacy IBM Cloud platform, and its URL will be redirected to the new `ibm_quantum_platform` address.
- **token** – IBM Cloud API key. Providing an API key is required for IQP authentication. If not provided explicitly, the default saved account will be queried for this API key.
- **url** – Base API URL. Defaults to `https://cloud.ibm.com` for non-local channels accessing the IBM Quantum Platform (e.g., `ibm_quantum_platform`, `ibm_cloud`). This URL is processed by a `url_resolver` to route requests to the correct service entrypoint. If you provide a custom `url`, you must also supply a matching `url_resolver`. The default resolver rewrites the base URL to `https://quantum.cloud.ibm.com/api/v[x]`.
- **filename** – Full path of the file where the account is created. Default: \_DEFAULT\_ACCOUNT\_CONFIG\_JSON\_FILE.
- **name** – Name of the account to load from file.
- **instance** – The service instance to use. For `ibm_cloud` and `ibm_quantum_platform`, this is the Cloud Resource Name (CRN) or the service name. If set, it will define an instance for service instantiation, if not set, the service will fetch all instances accessible within the account following the specified filtering criteria. Pass `"auto"` to explicitly request auto-selection without triggering the “instance not set” warning. This value can also be saved to the account file via [`save_account()`](#qiskit_ibm_runtime.QiskitRuntimeService.save_account "qiskit_ibm_runtime.QiskitRuntimeService.save_account") so it takes effect automatically on every instantiation.
- **proxies** – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://requests.readthedocs.io/en/latest/api/#requests.Session.proxies](https://requests.readthedocs.io/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication)
- **verify** – Whether to verify the server’s TLS certificate.
- **private\_endpoint** – Connect to private API URL.
- **url\_resolver** – Function used to resolve the runtime URL. If not provided, a default resolver will be used to access different service endpoints.
- **region** – Set a region preference for automatic instance selection. This argument is **ignored** if an `instance` is specified. Accepted values are `us-east` or `eu-de`. An instance with this region will be prioritized if an instance is not passed in.
- **plans\_preference** – A list of account plan names ordered by priority for automatic instance selection. This argument is **ignored** if an `instance` is specified. Only instances with the given plan names will be considered. For example, if you want to avoid using your premium accounts you can just pass in `"open"` to only use your open plan instances. Accepted values include (but are not limited to): `open`, `premium`, `flex`, `on-prem`, `pay-as-you-go`.
- **tags** – Set a list of tags to filter available instances for automatic instance selection. This argument is **ignored** if an `instance` is specified.

**Returns**

An instance of [`QiskitRuntimeService`](#qiskit_ibm_runtime.QiskitRuntimeService "qiskit_ibm_runtime.QiskitRuntimeService") or `QiskitRuntimeLocalService` if local channel is set.

**Raises**

**IBMInputValueError** – If an input is invalid.

Construct a `QiskitRuntimeService` instance.

## Attributes

### channel

Return the channel type used.

**Returns**

The channel type used.

## Methods

### active\_account

`active_account()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L793-L799)

Return the IBM Quantum account currently in use for the session.

**Returns**

A dictionary with information about the account currently in the session.

**Return type**

dict\[str, str] | None

### active\_instance

`active_instance()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1398-L1400)

Return the crn of the current active instance.

**Return type**

str

### backend

`backend(name, instance=None, use_fractional_gates=False, calibration_id=None)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L919-L983)

Return a single backend matching the specified filtering.

Note that backend availability is only verified upon circuit submission. To check the backend status ahead of time, use the [`status()`](/docs/api/qiskit-ibm-runtime/ibm-backend#status "qiskit_ibm_runtime.IBMBackend.status") method on the backend object:

```python
from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
backend = service.backend()

status = backend.status()
assert status.operational and status.status_msg == "active"
```

**Parameters**

- **name** (*str*) – Name of the backend.
- **instance** (*str | None*) – Specify the IBM Cloud account CRN.
- **use\_fractional\_gates** (*bool | None*) – Set True to allow for the backends to include fractional gates. See [When not to use fractional gates](/docs/guides/fractional-gates#when-not-to-use-fractional-gates) for limitations.
- **calibration\_id** (*str | None*) – The calibration id used for instantiating the backend.

**Returns**

A backend matching the filtering.

**Raises**

- **QiskitBackendNotFoundError** – if no backend could be found.
- **IBMInputValueError** – if fractional gates are requested but not supported by the backend.

**Return type**

Backend

### backends

`backends(name=None, min_num_qubits=None, instance=None, dynamic_circuits=None, filters=None, *, use_fractional_gates=False, calibration_id=None, **kwargs)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L541-L664)

Return all backends accessible via this account, subject to optional filtering.

**Parameters**

- **name** (*str | None*) – Backend name to filter by.

- **min\_num\_qubits** (*int | None*) – Minimum number of qubits the backend has to have.

- **instance** (*str | None*) – IBM Cloud account CRN

- **dynamic\_circuits** (*bool | None*) – Filter by whether the backend supports dynamic circuits.

- **filters** (*Callable\[\[*[*ibm\_backend.IBMBackend*](/docs/api/qiskit-ibm-runtime/ibm-backend "qiskit_ibm_runtime.ibm_backend.IBMBackend")*], bool] | None*) –

  More complex filters, such as lambda functions. For example:

  ```python
  QiskitRuntimeService.backends(
      filters=lambda backend: (
          (status := backend.status()).operational
          and status.status_msg == "active"
      )
  )
  ```

  will only return backends that are operational and active.

- **use\_fractional\_gates** (*bool | None*) – Set True to allow for the backends to include fractional gates. Note that our backends now support dynamic circuits and fractional gates simultaneously. You no longer have to disable this flag when using dynamic circuits features (e.g. `if_else`) in your algorithm. Control flow instructions are not removed from the backend when this flag is set to True. If `None`, then both fractional gates and control flow operations are included in the backends.

- **calibration\_id** (*str | None*) – The calibration id used for instantiating the backend. This should only be used when selecting a single backend as the calibration id is defined per backend.

- **\*\*kwargs** (*Any*) –

  Simple filters that require a specific value for an attribute in backend configuration or status. Examples:

  ```python
  # Get the operational real backends
  QiskitRuntimeService.backends(simulator=False, operational=True)

  # Get the backends with at least 127 qubits
  QiskitRuntimeService.backends(min_num_qubits=127)

  # Get the backends that support OpenPulse
  QiskitRuntimeService.backends(open_pulse=True)
  ```

  For the full list of backend attributes, see the [IBMBackend class documentation](/docs/api/qiskit-ibm-runtime)

**Returns**

The list of available backends that match the filter.

**Raises**

- **IBMInputValueError** – If an input is invalid.
- **QiskitBackendNotFoundError** – If the backend is not in any instance.

**Return type**

list\[[ibm\_backend.IBMBackend](/docs/api/qiskit-ibm-runtime/ibm-backend "qiskit_ibm_runtime.ibm_backend.IBMBackend")]

### delete\_account

*static* `delete_account(filename=None, name=None, channel=None)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L801-L819)

Delete a saved account from disk.

**Parameters**

- **filename** (*str | None*) – Name of file from which to delete the account.
- **name** (*str | None*) – Name of the saved account to delete.
- **channel** (*ChannelType | None*) – Channel type of the default account to delete. Ignored if account name is provided.

**Returns**

True if the account was deleted. False if no account was found.

**Return type**

bool

### delete\_job

`delete_job(job_id)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1214-L1231)

Delete a runtime job.

Note that this operation cannot be reversed.

**Parameters**

**job\_id** (*str*) – ID of the job to delete.

**Raises**

- **RuntimeJobNotFound** – The job doesn’t exist.
- **IBMRuntimeError** – Method is not supported.

**Return type**

None

### instances

`instances()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1385-L1396)

Return a list of instances available for the active account.

Return a list that contains a series of dictionaries with the following instance identifiers per instance: “crn”, “plan”, “name”.

**Returns**

A list with instances available for the active account.

**Return type**

Sequence\[dict\[str, Any]]

### job

`job(job_id)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1088-L1119)

Retrieve a runtime job.

**Parameters**

**job\_id** (*str*) – Job ID.

**Returns**

Runtime job retrieved.

**Raises**

- **RuntimeJobNotFound** – If the job doesn’t exist.
- **IBMRuntimeError** – If the request failed.

**Return type**

[*RuntimeJobV2*](/docs/api/qiskit-ibm-runtime/runtime-job-v2 "qiskit_ibm_runtime.runtime_job_v2.RuntimeJobV2")

### jobs

`jobs(limit=10, skip=0, backend_name=None, pending=None, program_id=None, instance=None, job_tags=None, session_id=None, created_after=None, created_before=None, descending=True)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1121-L1212)

Retrieve all runtime jobs, subject to optional filtering.

**Parameters**

- **limit** (*int | None*) – Number of jobs to retrieve. `None` means no limit.
- **skip** (*int*) – Starting index for the job retrieval.
- **backend\_name** (*str | None*) – Name of the backend to retrieve jobs from.
- **pending** (*bool | None*) – Filter by job pending state. If `True`, ‘QUEUED’ and ‘RUNNING’ jobs are included. If `False`, ‘DONE’, ‘CANCELLED’ and ‘ERROR’ jobs are included.
- **program\_id** (*str | None*) – Filter by Program ID.
- **instance** (*str | None*) – Filter by IBM Cloud instance crn.
- **job\_tags** (*list\[str] | None*) – Filter by tags assigned to jobs. Matched jobs are associated with all tags.
- **session\_id** (*str | None*) – Filter by session id. All jobs in the session will be returned in desceding order of the job creation date.
- **created\_after** (*datetime | None*) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time.
- **created\_before** (*datetime | None*) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time.
- **descending** (*bool*) – If `True`, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached.

**Returns**

A list of runtime jobs.

**Raises**

**IBMInputValueError** – If an input value is invalid.

**Return type**

list\[[RuntimeJobV2](/docs/api/qiskit-ibm-runtime/runtime-job-v2 "qiskit_ibm_runtime.RuntimeJobV2")]

### least\_busy

`least_busy(min_num_qubits=None, instance=None, filters=None, use_fractional_gates=False, **kwargs)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1308-L1383)

Return the least busy available backend.

**Parameters**

- **min\_num\_qubits** (*int | None*) – Minimum number of qubits the backend has to have.

- **instance** (*str | None*) – IBM Cloud account CRN.

- **filters** (*Callable\[\[*[*ibm\_backend.IBMBackend*](/docs/api/qiskit-ibm-runtime/ibm-backend "qiskit_ibm_runtime.ibm_backend.IBMBackend")*], bool] | None*) –

  Filters can be defined as for the [`backends()`](#qiskit_ibm_runtime.QiskitRuntimeService.backends "qiskit_ibm_runtime.QiskitRuntimeService.backends") method. An example to get the operational backends with 5 qubits:

  ```python
  QiskitRuntimeService.least_busy(n_qubits=5, operational=True)
  ```

- **use\_fractional\_gates** (*bool | None*) –

  When `True`, only backends that include fractional gates are considered, and fractional gates are included in the returned backend. See [When not to use fractional gates](/docs/guides/fractional-gates#when-not-to-use-fractional-gates) for limitations.

- **kwargs** (*Any*) – Additional arguments passed to the backend query.

**Returns**

The backend with the fewest number of pending jobs.

**Raises**

**QiskitBackendNotFoundError** – If no backend matches the criteria.

**Return type**

[ibm\_backend.IBMBackend](/docs/api/qiskit-ibm-runtime/ibm-backend "qiskit_ibm_runtime.ibm_backend.IBMBackend")

### save\_account

*static* `save_account(token=None, url=None, instance=None, channel=None, filename=None, name=None, proxies=None, verify=None, overwrite=False, set_as_default=None, private_endpoint=False, region=None, plans_preference=None, tags=None)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L821-L889)

Save the account to disk for future use.

**Parameters**

- **token** (*str | None*) – IBM Cloud API key.
- **url** (*str | None*) – The API URL. Defaults to [https://cloud.ibm.com](https://cloud.ibm.com).
- **instance** (*str | None*) – This is an optional parameter to specify the CRN or service name. If set, it will define a default instance for service instantiation, if not set, the service will fetch all instances accessible within the account. Set to `"auto"` to explicitly save auto-selection as the preference, which suppresses the “instance not set” warning on subsequent instantiations.
- **channel** (*ChannelType | None*) – Channel type. `ibm_cloud` or `ibm_quantum_platform`.
- **filename** (*str | None*) – Full path of the file where the account is saved.
- **name** (*str | None*) – Name of the account to save.
- **proxies** (*dict | None*) – Proxy configuration. Supported optional keys are `urls` (a dictionary mapping protocol or protocol and host to the URL of the proxy, documented at [https://requests.readthedocs.io/en/latest/api/#requests.Session.proxies](https://requests.readthedocs.io/en/latest/api/#requests.Session.proxies)), `username_ntlm`, `password_ntlm` (username and password to enable NTLM user authentication)
- **verify** (*bool | None*) – Verify the server’s TLS certificate.
- **overwrite** (*bool | None*) – `True` if the existing account is to be overwritten.
- **set\_as\_default** (*bool | None*) – If `True`, the account is saved in filename, as the default account.
- **private\_endpoint** (*bool | None*) – Connect to private API URL.
- **region** (*RegionType | None*) – Set a region preference. us-east or eu-de. An instance with this region will be prioritized if an instance is not passed in.
- **plans\_preference** (*PlanType | None*) – A list of account plan names (`open`, `premium`, etc.), ordered by preference. An instance with the first value in the list will be prioritized and only instances with the given plan names will be considered. For example, if you want to avoid using your premium accounts you can just pass in `"open"` to only use your open plan instances. `plans_preference` is ignored if an `instance` is specified.
- **tags** (*list\[str] | None*) – Set a list of tags to filter available instances. Instances with these tags will be prioritized if an instance is not passed in.

**Return type**

None

### saved\_accounts

*static* `saved_accounts(default=None, channel=None, filename=None, name=None)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L891-L917)

List the accounts saved on disk.

**Parameters**

- **default** (*bool | None*) – If set to True, only default accounts are returned.
- **channel** (*ChannelType | None*) – Channel type.\`\`ibm\_cloud\`\` or `ibm_quantum_platform`.
- **filename** (*str | None*) – Name of file whose accounts are returned.
- **name** (*str | None*) – If set, only accounts with the given name are returned.

**Returns**

A dictionary with information about the accounts saved on disk.

**Raises**

**ValueError** – If an invalid account is found on disk.

**Return type**

dict

### usage

`usage()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.48/qiskit_ibm_runtime/qiskit_runtime_service.py#L1233-L1247)

Return usage information for the current active instance.

**Returns**

Dict with usage details.

**Return type**

dict\[str, *Any*]