RuntimeJobV2¶

class RuntimeJobV2(backend, api_client, job_id, program_id, service, creation_date=None, result_decoder=None, image='', session_id=None, tags=None, version=None, private=False)[source]¶

Bases: BasePrimitiveJob[PrimitiveResult, Literal[‘INITIALIZING’, ‘QUEUED’, ‘RUNNING’, ‘CANCELLED’, ‘DONE’, ‘ERROR’]], BaseRuntimeJob

Representation of a runtime V2 primitive execution.

RuntimeJob constructor.

Parameters:

backend (Backend) – The backend instance used to run this job.
api_client (RuntimeClient) – Object for connecting to the server.
job_id (str) – Job ID.
program_id (str) – ID of the program this job is for.
creation_date (str | None) – Job creation date, in UTC.
result_decoder (Type[ResultDecoder] | Sequence[Type[ResultDecoder]] | None) – A ResultDecoder subclass used to decode job results.
image (str | None) – Runtime image used for this job: image_name:tag.
service (qiskit_runtime_service.QiskitRuntimeService) – Runtime service.
session_id (str | None) – Job ID of the first job in a runtime session.
tags (List | None) – Tags assigned to the job.
version (int | None) – Primitive version.
private (bool | None) – Marks job as private.

Attributes

ERROR: str | RuntimeJobStatus = 'ERROR'¶

JOB_FINAL_STATES: Tuple[Literal['INITIALIZING', 'QUEUED', 'RUNNING', 'CANCELLED', 'DONE', 'ERROR'], ...] = ('DONE', 'CANCELLED', 'ERROR')¶

creation_date¶

Job creation date in local time.

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.

Returns:: Input parameters used in this job.

instance¶: Return the IBM Cloud instance CRN.

primitive_id¶: Primitive name. :returns: Primitive this job is for.

private¶: Returns a boolean indicating whether or not the job is private.

session_id¶

Session ID.

Returns:: Session ID. None if the backend is a simulator.

tags¶

Job tags.

Returns:: Tags assigned to the job that can be used for filtering.

usage_estimation¶

Return the usage estimation information for this job.

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.

Methods

backend(timeout=None)[source]¶

Return the backend where this job was executed. Retrieve data again if backend is None.

Raises:: IBMRuntimeError – If a network error occurred.
Parameters:: timeout (float | None)
Return type:: Backend | None

cancel()[source]¶

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

cancelled()[source]¶

Return whether the job has been cancelled.

Return type:: bool

done()[source]¶

Return whether the job has successfully run.

Return type:: bool

error_message()[source]¶

Returns the reason if the job failed.

Returns:: Error message string or None.
Return type:: str | None

errored()[source]¶

Return whether the job has failed.

Return type:: bool

in_final_state()[source]¶

Return whether the job is in a final job state such as DONE or ERROR.

Return type:: bool

job_id()¶

Return a unique id identifying the job.

Return type:: str

logs()[source]¶

Return job logs.

Note

Job logs are only available after the job finishes.

Returns:: Job logs, including standard output and error.
Raises:: IBMRuntimeError – If a network error occurred.
Return type:: str

metrics()[source]¶

Return job metrics.

Returns:

timestamps: Timestamps of when the job was created, started running, and finished.
usage: Details regarding job usage, the measurement of the amount of
time the QPU is locked for your workload.

Return type:

A dictionary with job metrics including but not limited to the following

Raises:

IBMRuntimeError – If a network error occurred.

properties(refresh=False)[source]¶

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.
Returns:: The backend properties used for this job, at the time the job started running, or None if properties are not available.
Return type:: BackendProperties | None

result(timeout=None, decoder=None)[source]¶

Return the results of the job.

Parameters:

timeout (float | None) – Number of seconds to wait for job.
decoder (Type[ResultDecoder] | None) – A ResultDecoder subclass used to decode job results.

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.

Return type:

Any

running()[source]¶

Return whether the job is actively running.

Return type:: bool

status()[source]¶

Return the status of the job.

Returns:: Status of this job.
Return type:: Literal[‘INITIALIZING’, ‘QUEUED’, ‘RUNNING’, ‘CANCELLED’, ‘DONE’, ‘ERROR’]

update_tags(new_tags)[source]¶

Update the tags associated with this job.

Parameters:: new_tags (List[str]) – New tags to assign to the job.
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.
Return type:: List[str]

usage()[source]¶

Return job usage in seconds.

Return type:: float

wait_for_final_state(timeout=None)[source]¶

Poll for the job status from the API until the status is in a final state.

Parameters:: timeout (float | None) – Seconds to wait for the job. If None, wait indefinitely.
Raises:: RuntimeJobTimeoutError – If the job does not complete within given timeout.
Return type:: None