, skip=0, backend_name=None, status=None, start_datetime=None, end_datetime=None, job_tags=None, descending=True, instance=None, legacy=False)[source]#

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.

  • limit (Optional[int]) – Number of jobs to retrieve. None means no limit. Note that the number of sub-jobs within a composite job count towards the limit.

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

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

  • status (Union[Literal[‘pending’, ‘completed’], List[Union[JobStatus, str]], JobStatus, str, None]) – Filter jobs with either “pending” or “completed” status. You can also specify by

  • example (exact status. For) – or status=[“RUNNING”, “ERROR”].

  • status="RUNNING" (status=JobStatus.RUNNING or) – or status=[“RUNNING”, “ERROR”].

  • 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. Matched jobs are associated with all tags.

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

  • instance (Optional[str]) – The provider in the hub/group/project format.

  • legacy (bool) – If True, only retrieve jobs run from the deprecated qiskit-ibmq-provider.

  • Otherwise

  • qiskit-ibm-provider. (only retrieve jobs run from) –

Return type:



A list of IBMJob instances.

  • IBMBackendValueError – If a keyword value is not recognized.

  • TypeError – If the input start_datetime or end_datetime parameter value is not valid.