qiskit.providers.ibmq.runtime.RuntimeJob¶

class RuntimeJob(backend, api_client, credentials, job_id, program_id, params=None, creation_date=None, user_callback=None, result_decoder=<class 'qiskit.providers.ibmq.runtime.program.result_decoder.ResultDecoder'>)[source]¶

Representation of a runtime program execution.

A new RuntimeJob instance is returned when you call IBMRuntimeService.run to execute a runtime program, or IBMRuntimeService.job to retrieve a previously executed job.

If the program execution is successful, you can inspect the job’s status by calling status(). Job status can be one of the JobStatus members.

Some of the methods in this class are blocking, which means control may not be returned immediately. result() is an example of a blocking method:

job = provider.runtime.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 program has any interim results, you can use the callback parameter of the run() method to stream the interim results. Alternatively, you can use the stream_results() method to stream the results at a later time, but before the job finishes.

RuntimeJob constructor.

Parameters

backend (Backend) – The backend instance used to run this job.
api_client (RuntimeClient) – Object for connecting to the server.
credentials (Credentials) – Account credentials.
job_id (str) – Job ID.
program_id (str) – ID of the program this job is for.
params (Optional[Dict]) – Job parameters.
creation_date (Optional[str]) – Job creation date, in UTC.
user_callback (Optional[Callable]) – User callback function.
result_decoder (Type[ResultDecoder]) – A ResultDecoder subclass used to decode job results.

__init__(backend, api_client, credentials, job_id, program_id, params=None, creation_date=None, user_callback=None, result_decoder=<class 'qiskit.providers.ibmq.runtime.program.result_decoder.ResultDecoder'>)[source]¶

RuntimeJob constructor.

Parameters

backend (Backend) – The backend instance used to run this job.
api_client (RuntimeClient) – Object for connecting to the server.
credentials (Credentials) – Account credentials.
job_id (str) – Job ID.
program_id (str) – ID of the program this job is for.
params (Optional[Dict]) – Job parameters.
creation_date (Optional[str]) – Job creation date, in UTC.
user_callback (Optional[Callable]) – User callback function.
result_decoder (Type[ResultDecoder]) – A ResultDecoder subclass used to decode job results.

Methods

`__init__`(backend, api_client, credentials, …)	RuntimeJob constructor.
`backend`()	Return the backend where this job was executed.
`cancel`()	Cancel the job.
`cancel_result_streaming`()	Cancel result streaming.
`error_message`()	Returns the reason if the job failed.
`job_id`()	Return a unique ID identifying the job.
`logs`()	Return job logs.
`result`([timeout, wait, decoder])	Return the results of the job.
`status`()	Return the status of the job.
`stream_results`(callback[, decoder])	Start streaming job results.
`wait_for_final_state`([timeout, wait])	Poll the job status until it progresses to a final state such as `DONE` or `ERROR`.

Attributes

`creation_date`	Job creation date in local time.
`inputs`	Job input parameters.
`program_id`	Program ID.

backend()[source]¶

Return the backend where this job was executed.

Return type: Backend
Returns: Backend used for the job.

cancel()[source]¶

Cancel the job.

Raises

RuntimeInvalidStateError – If the job is in a state that cannot be cancelled.
QiskitRuntimeError – If unable to cancel job.

Return type

None

cancel_result_streaming()[source]¶

Cancel result streaming.

Return type: None

property 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.

error_message()[source]¶

Returns the reason if the job failed.

Return type: Optional[str]
Returns: Error message string or None.

property inputs¶

Job input parameters.

Return type: Dict
Returns: Input parameters used in this job.

job_id()[source]¶

Return a unique ID identifying the job.

Return type: str
Returns: Job ID.

logs()[source]¶

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: QiskitRuntimeError – If a network error occurred.

property program_id¶

Program ID.

Return type: str
Returns: ID of the program this job is for.

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

Return the results of the job.

Parameters

timeout (Optional[float]) – Number of seconds to wait for job.
wait (float) – Seconds between queries.
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.

status()[source]¶

Return the status of the job.

Return type: JobStatus
Returns: Status of this job.

stream_results(callback, decoder=None)[source]¶

Start streaming job results.

Parameters

callback (Callable) –
Callback function to be invoked for any interim results. The callback function will receive 2 positional parameters:
1. Job ID
2. Job interim 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

wait_for_final_state(timeout=None, wait=5)[source]¶

Poll the job status until it progresses to a final state such as DONE or ERROR.

Parameters

timeout (Optional[float]) – Seconds to wait for the job. If None, wait indefinitely.
wait (float) – Seconds between queries.

Raises

JobTimeoutError – If the job does not reach a final state before the specified timeout.

Return type

None