QiskitRuntimeService

class QiskitRuntimeService(*args, **kwargs)

GitHub

Bases: object

Class for interacting with the Qiskit Runtime service.

QiskitRuntimeService constructor

An account is selected in the following order:

Account with the input name, if specified.

Default account for the channel type, if channel is specified but token is not.

Account defined by the input channel and token, if specified.

Account defined by the default_channel if defined in filename

Account defined by the environment variables, if defined.

Default account for the ibm_cloud account, if one is available.

Default account for the ibm_quantum account, if one is available.

instance, proxies, and verify can be used to overwrite corresponding values in the loaded account.

Parameters

channel – Channel type. ibm_cloud, ibm_quantum or local. 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 documentation.
token – IBM Cloud API key or IBM Quantum API token.
url – The API URL. Defaults to https://cloud.ibm.com (ibm_cloud) or https://auth.quantum-computing.ibm.com/api (ibm_quantum).
filename – Full path of the file where the account is created. Default: _DEFAULT_ACCOUNT_CONFIG_JSON_FILE
name – Name of the account to load.
instance – The service instance to use. For ibm_cloud runtime, this is the Cloud Resource Name (CRN) or the service name. For ibm_quantum runtime, this is the hub/group/project in that format.
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://docs.python-requests.org/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.

Returns

An instance of QiskitRuntimeService or QiskitRuntimeLocalService for local channel.

Raises

IBMInputValueError - If an input is invalid.

Attributes

channel

Return the channel type used.

Returns

The channel type used.

Methods

active_account

active_account()

GitHub

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

backend

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

GitHub

Return a single backend matching the specified filtering.

Parameters

name (str) – Name of the backend.
instance (str | None) – This is only supported for ibm_quantum runtime and is in the hub/group/project format. If an instance is not given, among the providers with access to the backend, a premium provider will be prioritized. For users without access to a premium provider, the default open provider will be used.
use_fractional_gates (bool | None) – Set True to allow for the backends to include fractional gates. Currently this feature cannot be used simultaneously with dynamic circuits, PEC, PEA, or gate twirling. When this flag is set, control flow instructions are automatically removed from the backend. When you use a dynamic circuits feature (e.g. if_else) in your algorithm, you must disable this flag to create executable ISA circuits. This flag might be modified or removed when our backend supports dynamic circuits and fractional gates simultaneously. If None, then both fractional gates and control flow operations are included in the backends.

Returns

A backend matching the filtering.

Return type

Backend

Raises

QiskitBackendNotFoundError - if no backend could be found.

backends

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

GitHub

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) - This is only supported for ibm_quantum runtime and is in the hub/group/project format.$
$dynamic_circuits (bool | None) - Filter by whether the backend supports dynamic circuits.$

filters (Callable[[IBMBackend], bool] | None) -

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

QiskitRuntimeService.backends(
    filters=lambda b: b.max_shots > 50000
)
QiskitRuntimeService.backends(
    filters=lambda x: ("rz" in x.basis_gates )
)

$use_fractional_gates (bool | None) – Set True to allow for the backends to include fractional gates. Currently this feature cannot be used simultaneously with dynamic circuits, PEC, PEA, or gate twirling. When this flag is set, control flow instructions are automatically removed from the backend. When you use a dynamic circuits feature (e.g. if_else) in your algorithm, you must disable this flag to create executable ISA circuits. This flag might be modified or removed when our backend supports dynamic circuits and fractional gates simultaneously. If None, then both fractional gates and control flow operations are included in the backends.$

**kwargs (Any) -

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

# 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 < api/qiskit/providers_models >

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 [IBMBackend]

check_pending_jobs

check_pending_jobs()

GitHub

Check the number of pending jobs and wait for the oldest pending job if the maximum number of pending jobs has been reached.

Return type

None

delete_account

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

GitHub

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 (Literal['ibm_cloud', 'ibm_quantum', 'local'] | 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

Delete a runtime job.

Note that this operation cannot be reversed.

Parameters

job_id (str) - ID of the job to delete.

Raises

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

Return type

None

instances

instances()

GitHub

Return the IBM Quantum instances list currently in use for the session.

Returns

A list with instances currently in the session.

Return type

List [str]

job

job(job_id)

GitHub

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

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

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) – This is only supported for ibm_quantum runtime and is in the hub/group/project format.
job_tags (List[str] | None) – Filter by tags assigned to jobs. Matched jobs are associated with all tags.
session_id (str | None) – Job ID of the first job in a runtime session.
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 [RuntimeJob | RuntimeJobV2]

least_busy

least_busy(min_num_qubits=None, instance=None, filters=None, **kwargs)

GitHub

Return the least busy available backend.

Parameters

$min_num_qubits (int | None) - Minimum number of qubits the backend has to have.$
$instance (str | None) - This is only supported for ibm_quantum runtime and is in the hub/group/project format.$
filters (Callable[[IBMBackend], bool] | None) –

Filters can be defined as for the backends() method. An example to get the operational backends with 5 qubits:
```
QiskitRuntimeService.least_busy(n_qubits=5, operational=True)
```
$kwargs (Any)$

Returns

The backend with the fewest number of pending jobs.

Raises

QiskitBackendNotFoundError - If no backend matches the criteria.

Return type

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)

GitHub

Save the account to disk for future use.

Parameters

token (str | None) – IBM Cloud API key or IBM Quantum API token.
url (str | None) – The API URL. Defaults to https://cloud.ibm.com (ibm_cloud) or https://auth.quantum-computing.ibm.com/api (ibm_quantum).
instance (str | None) – The CRN (ibm_cloud) or hub/group/project (ibm_quantum).
channel (Literal['ibm_cloud', 'ibm_quantum', 'local'] | None) – Channel type. ibm_cloud or ibm_quantum.
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://docs.python-requests.org/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.

Return type

None

saved_accounts

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

GitHub

List the accounts saved on disk.

Parameters

default (bool | None) – If set to True, only default accounts are returned.
channel (Literal['ibm_cloud', 'ibm_quantum', 'local'] | None) – Channel type. ibm_cloud or ibm_quantum.
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

Return monthly open plan usage information.

Returns

Dict with usage details.

Raises

IBMInputValueError - If method is called when using the ibm_cloud channel

Return type

Dict [str, Any]

Was this page helpful?

Report a bug or request content on GitHub.