IBMQBackendService

IBMQBackendService.backends(name=None, filters=None, timeout=None, min_num_qubits=None, input_allowed=None, **kwargs)

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

Parameters

• name (Optional[str]) – Backend name to filter by.

• filters (Optional[Callable[[List[IBMQBackend]], bool]]) –

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

  AccountProvider.backends(
      filters=lambda b: b.configuration().quantum_volume > 16)

• timeout (Optional[float]) – Maximum number of seconds to wait for the discovery of remote backends.

• min_num_qubits (Optional[int]) – Minimum number of qubits the backend has to have.

• input_allowed (Union[str, List[str], None]) – Filter by the types of input the backend supports. Valid input types are job (circuit job) and runtime (Qiskit Runtime). For example, inputs_allowed='runtime' will return all backends that support Qiskit Runtime. If a list is given, the backend must support all types specified in the list.

• kwargs (Any) –

  Simple filters that specify a True/False criteria in the backend configuration, backends status, or provider credentials. An example to get the operational backends with 5 qubits:

  AccountProvider.backends(n_qubits=5, operational=True)

Return type

List[IBMQBackend]

Returns

The list of available backends that match the filter.

IBMQBackendService.job_ids(limit=10, skip=0, backend_name=None, status=None, job_name=None, start_datetime=None, end_datetime=None, job_tags=None, job_tags_operator='OR', descending=True)

Return a list of job IDs, subject to optional filtering.

Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server.

Parameters

• limit (Optional[int]) – Number of jobs to retrieve. None means no limit.

• skip (int) – Starting index for the job retrieval.

• backend_name (Optional[str]) – Name of the backend to retrieve jobs from.

• status (Union[JobStatus, str, List[Union[JobStatus, str]], None]) – Only get jobs with this status or one of the statuses. For example, you can specify status=JobStatus.RUNNING or status=”RUNNING” or status=[“RUNNING”, “ERROR”]

• job_name (Optional[str]) – Filter by job name. The job_name is matched partially and regular expressions can be used.

• start_datetime (Optional[datetime]) – 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.

• end_datetime (Optional[datetime]) – 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.

• job_tags (Optional[List[str]]) – Filter by tags assigned to jobs.

• job_tags_operator (Optional[str]) –

  Logical operator to use when filtering by job tags. Valid values are “AND” and “OR”:

  • If “AND” is specified, then a job must have all of the tags specified in job_tags to be included.
  • If “OR” is specified, then a job only needs to have any of the tags specified in job_tags to be included.

• descending (bool) – If True, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached.

Return type

List[IBMQJob]

Returns

A list of IBMJob instances.

Raises

• IBMQBackendValueError – If a keyword value is not recognized.
• TypeError – If the input start_datetime or end_datetime parameter value is not valid.

IBMQBackendService.jobs(limit=10, skip=0, backend_name=None, status=None, job_name=None, start_datetime=None, end_datetime=None, job_tags=None, job_tags_operator='OR', experiment_id=None, descending=True, db_filter=None)

Return a list of jobs, subject to optional filtering.

Retrieve jobs that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server.

Parameters

• limit (int) – Number of jobs to retrieve.

• skip (int) – Starting index for the job retrieval.

• backend_name (Optional[str]) – Name of the backend to retrieve jobs from.

• status (Union[JobStatus, str, List[Union[JobStatus, str]], None]) – Only get jobs with this status or one of the statuses. For example, you can specify status=JobStatus.RUNNING or status=”RUNNING” or status=[“RUNNING”, “ERROR”]

• job_name (Optional[str]) – Filter by job name. The job_name is matched partially and regular expressions can be used.

• start_datetime (Optional[datetime]) – 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.

• end_datetime (Optional[datetime]) – 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.

• job_tags (Optional[List[str]]) – Filter by tags assigned to jobs.

• job_tags_operator (Optional[str]) –

  Logical operator to use when filtering by job tags. Valid values are “AND” and “OR”:

  • If “AND” is specified, then a job must have all of the tags specified in job_tags to be included.
  • If “OR” is specified, then a job only needs to have any of the tags specified in job_tags to be included.

• experiment_id (Optional[str]) – Filter by job experiment ID.

• descending (bool) – If True, return the jobs in descending order of the job creation date (i.e. newest first) until the limit is reached.

• db_filter (Optional[Dict[str, Any]]) –

  A loopback-based filter. This is an interface to a database where filter. Some examples of its usage are:

  Filter last five jobs with errors:

  job_list = backend.jobs(limit=5, status=JobStatus.ERROR)

  Filter last five jobs with hub name ibm-q:

  filter = {'hubInfo.hub.name': 'ibm-q'}
  job_list = backend.jobs(limit=5, db_filter=filter)

Return type

List[IBMQJob]

Returns

A list of IBMQJob instances.

Raises

• IBMQBackendValueError – If a keyword value is not recognized.
• TypeError – If the input start_datetime or end_datetime parameter value is not valid.

IBMQBackendService.my_reservations()

Return your upcoming reservations.

Return type

List[BackendReservation]

Returns

A list of your upcoming reservations.

IBMQBackendService.retrieve_job(job_id)

Return a single job.

Parameters

job_id (str) – The ID of the job to retrieve.

Return type

IBMQJob

Returns

The job with the given id.

Raises

• IBMQBackendApiError – If an unexpected error occurred when retrieving the job.
• IBMQBackendApiProtocolError – If unexpected return value received from the server.