--- title: RuntimeJob (v0.26) description: API reference for qiskit_ibm_runtime.RuntimeJob in qiskit-ibm-runtime v0.26 source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime/0.26/runtime-job --- # RuntimeJob *class* `RuntimeJob(backend, api_client, client_params, job_id, program_id, service, creation_date=None, user_callback=None, result_decoder=None, image='', session_id=None, tags=None, version=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L46-L408) Representation of a runtime primitive execution. A new `RuntimeJob` instance is returned when you call [`QiskitRuntimeService.run`](/docs/api/qiskit-ibm-runtime/0.26/qiskit-runtime-service#run "qiskit_ibm_runtime.QiskitRuntimeService.run") to execute a runtime primitive, or [`QiskitRuntimeService.job`](/docs/api/qiskit-ibm-runtime/0.26/qiskit-runtime-service#job "qiskit_ibm_runtime.QiskitRuntimeService.job") to retrieve a previously executed job. If the primitive execution is successful, you can inspect the job’s status by calling [`status()`](#qiskit_ibm_runtime.RuntimeJob.status "qiskit_ibm_runtime.RuntimeJob.status"). Job status can be one of the [`JobStatus`](/docs/api/qiskit/qiskit.providers.JobStatus) members. Some of the methods in this class are blocking, which means control may not be returned immediately. [`result()`](#qiskit_ibm_runtime.RuntimeJob.result "qiskit_ibm_runtime.RuntimeJob.result") is an example of a blocking method: ```python job = service.run(...) try: job_result = job.result() # It will block until the job finishes. print("The job finished with result {}".format(job_result)) except RuntimeJobFailureError as ex: print("Job failed!: {}".format(ex)) ``` If the primitive has any interim results, you can use the `callback` parameter of the [`run()`](/docs/api/qiskit-ibm-runtime/0.26/qiskit-runtime-service#run "qiskit_ibm_runtime.QiskitRuntimeService.run") method to stream the interim results along with the final result. Alternatively, you can use the [`stream_results()`](#qiskit_ibm_runtime.RuntimeJob.stream_results "qiskit_ibm_runtime.RuntimeJob.stream_results") method to stream the results at a later time, but before the job finishes. RuntimeJob constructor. **Parameters** - **backend** ([`Backend`](/docs/api/qiskit/qiskit.providers.Backend)) – The backend instance used to run this job. - **api\_client** (`RuntimeClient`) – Object for connecting to the server. - **client\_params** (`ClientParameters`) – Parameters used for server connection. - **job\_id** (`str`) – Job ID. - **program\_id** (`str`) – ID of the program this job is for. - **creation\_date** (`Optional`\[`str`]) – Job creation date, in UTC. - **user\_callback** (`Optional`\[`Callable`]) – User callback function. - **result\_decoder** (`Union`\[`Type`\[`ResultDecoder`], `Sequence`\[`Type`\[`ResultDecoder`]], `None`]) – A `ResultDecoder` subclass used to decode job results. - **image** (`Optional`\[`str`]) – Runtime image used for this job: image\_name:tag. - **service** ([`QiskitRuntimeService`](/docs/api/qiskit-ibm-runtime/0.26/qiskit-runtime-service "qiskit_ibm_runtime.qiskit_runtime_service.QiskitRuntimeService")) – Runtime service. - **session\_id** (`Optional`\[`str`]) – Job ID of the first job in a runtime session. - **tags** (`Optional`\[`List`]) – Tags assigned to the job. - **version** (`Optional`\[`int`]) – Primitive version. ## Attributes ### ERROR Type: `str | RuntimeJobStatus` Default value: `'job incurred error'` ### JOB\_FINAL\_STATES Type: `Tuple[Any, ...]` Default value: `(JobStatus.DONE, JobStatus.CANCELLED, JobStatus.ERROR)` ### creation\_date Job creation date in local time. **Return type** `Optional`\[`datetime`] **Returns** The job creation date as a datetime object, in local time, or `None` if creation date is not available. ### image Return the runtime image used for the job. **Returns** image\_name:tag or “” if the default image is used. **Return type** Runtime image ### inputs Job input parameters. **Return type** `Dict` **Returns** Input parameters used in this job. ### instance For ibm\_quantum channel jobs, return the instance where the job was run. For ibm\_cloud, None is returned. **Return type** `Optional`\[`str`] ### primitive\_id Primitive name. :rtype: `str` :returns: Primitive this job is for. ### program\_id Program ID. **Return type** `str` **Returns** ID of the program this job is for. ### session\_id Session ID. **Return type** `str` **Returns** Session ID. None if the backend is a simulator. ### tags Job tags. **Return type** `List` **Returns** Tags assigned to the job that can be used for filtering. ### usage\_estimation Return the usage estimation infromation for this job. **Return type** `Dict`\[`str`, `Any`] **Returns** `quantum_seconds` which is the estimated system execution time of the job in seconds. Quantum time represents the time that the system is dedicated to processing your job. ### version Default value: `1` ## Methods ### backend `backend(timeout=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L342-L356) Return the backend where this job was executed. Retrieve data again if backend is None. **Raises** **IBMRuntimeError** – If a network error occurred. **Return type** `Optional`\[[`Backend`](/docs/api/qiskit/qiskit.providers.Backend)] ### cancel `cancel()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L171-L185) Cancel the job. **Raises** - **RuntimeInvalidStateError** – If the job is in a state that cannot be cancelled. - **IBMRuntimeError** – If unable to cancel job. **Return type** `None` ### cancel\_result\_streaming `cancel_result_streaming()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/base_runtime_job.py#L132-L136) Cancel result streaming. **Return type** `None` ### cancelled `cancelled()` Return whether the job has been cancelled. **Return type** `bool` ### done `done()` Return whether the job has successfully run. **Return type** `bool` ### error\_message `error_message()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/base_runtime_job.py#L195-L202) Returns the reason if the job failed. **Return type** `Optional`\[`str`] **Returns** Error message string or `None`. ### errored `errored()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L200-L202) Return whether the job has failed. **Return type** `bool` ### in\_final\_state `in_final_state()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L196-L198) Return whether the job is in a final job state such as `DONE` or `ERROR`. **Return type** `bool` ### interim\_results `interim_results(decoder=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/utils/deprecation.py#L389-L408) Return the interim results of the job. **Parameters** **decoder** (`Optional`\[`Type`\[`ResultDecoder`]]) – A `ResultDecoder` subclass used to decode interim results. **Return type** `Any` **Returns** Runtime job interim results. **Raises** **RuntimeJobFailureError** – If the job failed. ### job\_id `job_id()` Return a unique id identifying the job. **Return type** `str` ### logs `logs()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L293-L312) Return job logs. > **Note** > > Job logs are only available after the job finishes. **Return type** `str` **Returns** Job logs, including standard output and error. **Raises** **IBMRuntimeError** – If a network error occurred. ### metrics `metrics()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/base_runtime_job.py#L138-L150) Return job metrics. **Return type** `Dict`\[`str`, `Any`] **Returns** Job metrics, which includes timestamp information. **Raises** **IBMRuntimeError** – If a network error occurred. ### properties `properties(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/base_runtime_job.py#L181-L193) Return the backend properties for this job. **Parameters** **refresh** (`bool`) – If `True`, re-query the server for the backend properties. Otherwise, return a cached version. **Return type** `Optional`\[`BackendProperties`] **Returns** The backend properties used for this job, at the time the job was run, or `None` if properties are not available. ### queue\_info `queue_info()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L259-L291) Return queue information for this job. The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See `QueueInfo` for more information. > **Note** > > The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return `None`. **Return type** `Optional`\[`QueueInfo`] **Returns** A `QueueInfo` instance that contains queue information for this job, or `None` if queue information is unknown or not applicable. ### queue\_position `queue_position(refresh=False)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L232-L257) Return the position of the job in the server queue. > **Note** > > The position returned is within the scope of the provider and may differ from the global queue position. **Parameters** **refresh** (`bool`) – If `True`, re-query the server to get the latest value. Otherwise return the cached value. **Return type** `Optional`\[`int`] **Returns** Position in the queue or `None` if position is unknown or not applicable. ### result `result(timeout=None, decoder=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L136-L169) Return the results of the job. **Parameters** - **timeout** (`Optional`\[`float`]) – Number of seconds to wait for job. - **decoder** (`Optional`\[`Type`\[`ResultDecoder`]]) – A `ResultDecoder` subclass used to decode job results. **Return type** `Any` **Returns** Runtime job result. **Raises** - **RuntimeJobFailureError** – If the job failed. - **RuntimeJobMaxTimeoutError** – If the job does not complete within given timeout. - **RuntimeInvalidStateError** – If the job was cancelled, and attempting to retrieve result. ### running `running()` Return whether the job is actively running. **Return type** `bool` ### status `status()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L187-L194) Return the status of the job. **Return type** [`JobStatus`](/docs/api/qiskit/qiskit.providers.JobStatus) **Returns** Status of this job. ### stream\_results `stream_results(callback, decoder=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/utils/deprecation.py#L358-L387) Start streaming job results. **Parameters** - **callback** (`Callable`) – Callback function to be invoked for any interim results and final result. The callback function will receive 2 positional parameters: > 1. Job ID > 2. Job result. - **decoder** (`Optional`\[`Type`\[`ResultDecoder`]]) – A `ResultDecoder` subclass used to decode job results. **Raises** **RuntimeInvalidStateError** – If a callback function is already streaming results or if the job already finished. **Return type** `None` ### submit `submit()` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L218-L230) Unsupported method. .. note: ```python This method is not supported, please use :meth:`~qiskit_ibm_runtime.QiskitRuntimeService.run` to submit a job. ``` **Raises** **NotImplementedError** – Upon invocation. **Return type** `None` ### update\_tags `update_tags(new_tags)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/base_runtime_job.py#L152-L179) Update the tags associated with this job. **Parameters** **new\_tags** (`List`\[`str`]) – New tags to assign to the job. **Return type** `List`\[`str`] **Returns** The new tags associated with this job. **Raises** **IBMApiError** – If an unexpected error occurred when communicating with the server or updating the job tags. ### wait\_for\_final\_state `wait_for_final_state(timeout=None)` [GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.26/qiskit_ibm_runtime/runtime_job.py#L314-L340) Poll for the job status from the API until the status is in a final state. **Parameters** **timeout** (`Optional`\[`float`]) – Seconds to wait for the job. If `None`, wait indefinitely. **Raises** **RuntimeJobTimeoutError** – If the job does not complete within given timeout. **Return type** `None`