Jobs

Endpoints related to running jobs

List jobs

List the quantum jobs you have run.

Query Parameters

Name, Type	Description
limit integer	Number of results to return at a time Default Value: `200`
offset integer	Number of results to offset when retrieving the list of jobs
pending boolean	Returns 'Queued' and 'Running' jobs if true. Returns 'Completed', 'Cancelled', and 'Failed' jobs if false.
provider string	Provider to filter jobs. Should be in the following format {hub}/{group}/{project}
program string	Program ID to filter jobs
backend string	Backend to filter jobs
created_after string	Job created after filter
created_before string	Job created before filter
sort string	Sort jobs by created time ASC or DESC (default)
tags string[]	List of job or program tags
session_id string	Session ID to filter jobs
exclude_params boolean	Exclude job params from the response Default Value: `true`

HTTP Response Status Codes

Status code	Description
200	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs

Responses

Status code

{
  "jobs": [
    {
      "id": "c5dge2d3rn7breq27i9g",
      "backend": "ibmq_qasm_simulator",
      "state": {
        "status": "Completed",
        "reason": ""
      },
      "status": "Completed",
      "params": {
        "iterations": 3
      },
      "program": {
        "id": "sampler"
      },
      "created": "2021-10-04T13:52:09.456851Z",
      "runtime": "ntc-provider-primitives:latest",
      "tags": [
        "tag1",
        "tag2",
        "tag3",
        "tag4"
      ],
      "session_id": "c5dge2d3rn7breq27i9g",
      "usage": {
        "seconds": 1
      }
    }
  ],
  "count": 1,
  "limit": 1,
  "offset": 0
}

Status code

{
  "title": "JobsResponse",
  "type": "object",
  "description": "Jobs collection response",
  "properties": {
    "jobs": {
      "description": "A list of jobs",
      "type": "array",
      "items": {
        "title": "JobResponse",
        "type": "object",
        "description": "A job",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier assigned to the job"
          },
          "hub": {
            "type": "string",
            "description": "Name of the hub in which the job is being executed (IBM Quantum users only)"
          },
          "group": {
            "type": "string",
            "description": "Name of the group in which the job is being executed (IBM Quantum users only)"
          },
          "project": {
            "type": "string",
            "description": "Name of the project in which the job is being executed (IBM Quantum users only)"
          },
          "backend": {
            "type": "string",
            "description": "The backend on which to run the job.  If no backend is specified, the job is sent to the backend with the shortest queue that you have access to.",
            "pattern": ".*"
          },
          "state": {
            "title": "JobState",
            "type": "object",
            "description": "Current state of the job",
            "properties": {
              "status": {
                "type": "string",
                "description": "Current status of the job",
                "enum": [
                  "Queued",
                  "Running",
                  "Completed",
                  "Cancelled",
                  "Failed"
                ]
              },
              "reason": {
                "type": "string",
                "description": "Reason for the current status"
              },
              "reason_code": {
                "type": "integer",
                "description": "Reason code for the current status"
              },
              "reason_solution": {
                "type": "string",
                "description": "Next steps user can take in case of failure"
              }
            },
            "required": [
              "status"
            ]
          },
          "status": {
            "title": "JobStatus",
            "type": "string",
            "description": "Current status of the job",
            "enum": [
              "Queued",
              "Running",
              "Completed",
              "Cancelled",
              "Cancelled - Ran too long",
              "Failed"
            ]
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Parameters used to execute the job"
          },
          "program": {
            "type": "object",
            "description": "Primitive associated with the job",
            "properties": {
              "id": {
                "type": "string",
                "description": "Identifier of the executed primitive"
              }
            },
            "required": [
              "id"
            ]
          },
          "created": {
            "type": "string",
            "description": "UTC timestamp for when the job was created"
          },
          "runtime": {
            "type": "string",
            "description": "Name and tag of the image to use when running a program (IBM Quantum users only)"
          },
          "cost": {
            "type": "integer",
            "description": "Cost of the job"
          },
          "tags": {
            "title": "Tags",
            "description": "List of job or program tags",
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "string",
              "pattern": ".*",
              "minLength": 1,
              "maxLength": 24
            }
          },
          "session_id": {
            "type": "string",
            "description": "Identifier of the session that the job is a part of"
          },
          "usage": {
            "title": "Usage",
            "description": "usage metrics",
            "type": "object",
            "properties": {
              "seconds": {
                "type": "number",
                "description": "Number of seconds of Qiskit Runtime usage including quantum compute and near-time classical pre- and post-processing"
              }
            },
            "required": [
              "seconds"
            ]
          },
          "estimated_running_time_seconds": {
            "type": "number",
            "format": "double",
            "description": "The estimated running time of the job (in seconds)"
          },
          "estimated_max_running_time_seconds": {
            "type": "number",
            "format": "double",
            "description": "The estimated upper-bound running time of the job (in seconds)"
          }
        },
        "required": [
          "id",
          "created",
          "program",
          "state",
          "status",
          "cost"
        ]
      }
    },
    "count": {
      "type": "integer",
      "description": "Total number of jobs for the user"
    },
    "offset": {
      "type": "integer",
      "description": "Offset at which paginated results are returned"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results returned in the paginated response"
    }
  },
  "required": [
    "limit",
    "offset"
  ]
}

Run a job

Invoke a Qiskit Runtime primitive. Note the returned job ID. You will use it to check the job's status and review results. This request is rate limited to 5 jobs per minute per user.

Body Parameters (application/json)

Name, Type	Description
program_id Required string	ID of the primitive to be executed
hub string	Provider hub name (IBM Quantum users only)
group string	Provider group name (IBM Quantum users only)
project string	Provider project name (IBM Quantum users only)
backend string	Name that identifies the backend on which to run the job
params object	Parameters to inject into the primitive as key-value pairs
runtime string	Name and tag of the image to use when running a program (IBM Quantum users only). Should follow the pattern "name:tag".
Tags string[]	List of job or program tags
log_level string	Logging level of the job Possible Values: `criticalerrorwarninginfodebug`
cost integer	Cost of the job as the estimated time it should take to complete (in seconds). Should not exceed the cost of the primitive
session_id string	Identifier of the session that the job is a part of
start_session boolean	Flag to start a new runtime session Default Value: `false`
session_time integer	Parameter to specify length of a session in seconds. A session allows to group a collection of iterative calls to the quantum computer. Session length cannot exceed user device limit and should be greater than job cost.
remote_storage

HTTP Response Status Codes

Status code	Description
200	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Usage exceeds instance limit

Code samples

POST

/jobs

curl -X POST \
  -H "x-access-token: <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d {"program_id":"program_id"} \
  https://runtime-us-east.quantum-computing.ibm.com/jobs

Responses

Status code

{
  "id": "c5dge2d3rn7breq27i9g"
}

Status code

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Job ID"
    },
    "backend": {
      "type": "string",
      "description": "Backend selected to run job"
    },
    "session_id": {
      "type": "string",
      "description": "Id of the session associated with the job"
    }
  },
  "description": "Response when creating a job",
  "required": [
    "id"
  ]
}

List job details

List the details about the specified quantum job.

Path Parameters

Name, Type	Description
id Required string	Identifier of an existing job

Query Parameters

Name, Type	Description
exclude_params boolean	Exclude job params from the response Default Value: `false`

HTTP Response Status Codes

Status code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs/{id}

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}

Responses

Status code

{
  "id": "c5dge2d3rn7breq27i9g",
  "backend": "ibmq_qasm_simulator",
  "state": {
    "status": "Completed",
    "reason": ""
  },
  "status": "Completed",
  "params": {
    "iterations": 3
  },
  "program": {
    "id": "sampler"
  },
  "created": "2021-10-04T13:52:09.456851Z",
  "runtime": "ntc-provider-primitives:latest",
  "tags": [
    "tag1",
    "tag2",
    "tag3",
    "tag4"
  ],
  "session_id": "c5dge2d3rn7breq27i9g"
}

Status code

{
  "title": "JobResponse",
  "type": "object",
  "description": "A job",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identifier assigned to the job"
    },
    "hub": {
      "type": "string",
      "description": "Name of the hub in which the job is being executed (IBM Quantum users only)"
    },
    "group": {
      "type": "string",
      "description": "Name of the group in which the job is being executed (IBM Quantum users only)"
    },
    "project": {
      "type": "string",
      "description": "Name of the project in which the job is being executed (IBM Quantum users only)"
    },
    "backend": {
      "type": "string",
      "description": "The backend on which to run the job.  If no backend is specified, the job is sent to the backend with the shortest queue that you have access to.",
      "pattern": ".*"
    },
    "state": {
      "title": "JobState",
      "type": "object",
      "description": "Current state of the job",
      "properties": {
        "status": {
          "type": "string",
          "description": "Current status of the job",
          "enum": [
            "Queued",
            "Running",
            "Completed",
            "Cancelled",
            "Failed"
          ]
        },
        "reason": {
          "type": "string",
          "description": "Reason for the current status"
        },
        "reason_code": {
          "type": "integer",
          "description": "Reason code for the current status"
        },
        "reason_solution": {
          "type": "string",
          "description": "Next steps user can take in case of failure"
        }
      },
      "required": [
        "status"
      ]
    },
    "status": {
      "title": "JobStatus",
      "type": "string",
      "description": "Current status of the job",
      "enum": [
        "Queued",
        "Running",
        "Completed",
        "Cancelled",
        "Cancelled - Ran too long",
        "Failed"
      ]
    },
    "params": {
      "type": "object",
      "additionalProperties": true,
      "description": "Parameters used to execute the job"
    },
    "program": {
      "type": "object",
      "description": "Primitive associated with the job",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier of the executed primitive"
        }
      },
      "required": [
        "id"
      ]
    },
    "created": {
      "type": "string",
      "description": "UTC timestamp for when the job was created"
    },
    "runtime": {
      "type": "string",
      "description": "Name and tag of the image to use when running a program (IBM Quantum users only)"
    },
    "cost": {
      "type": "integer",
      "description": "Cost of the job"
    },
    "tags": {
      "title": "Tags",
      "description": "List of job or program tags",
      "type": "array",
      "minItems": 1,
      "maxItems": 5,
      "items": {
        "type": "string",
        "pattern": ".*",
        "minLength": 1,
        "maxLength": 24
      }
    },
    "session_id": {
      "type": "string",
      "description": "Identifier of the session that the job is a part of"
    },
    "usage": {
      "title": "Usage",
      "description": "usage metrics",
      "type": "object",
      "properties": {
        "seconds": {
          "type": "number",
          "description": "Number of seconds of Qiskit Runtime usage including quantum compute and near-time classical pre- and post-processing"
        }
      },
      "required": [
        "seconds"
      ]
    },
    "estimated_running_time_seconds": {
      "type": "number",
      "format": "double",
      "description": "The estimated running time of the job (in seconds)"
    },
    "estimated_max_running_time_seconds": {
      "type": "number",
      "format": "double",
      "description": "The estimated upper-bound running time of the job (in seconds)"
    }
  },
  "required": [
    "id",
    "created",
    "program",
    "state",
    "status",
    "cost"
  ]
}

Delete a job

Delete the specified job.

Path Parameters

Name, Type	Description
id Required string	Identifier of an existing job

HTTP Response Status Codes

Status code	Description
204	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

DELETE

/jobs/{id}

curl -X DELETE -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}

Responses

Status code

List job results

Return the final result from this job.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	Returns the job's final result.
204	Job's final result not found.
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs/{id}/results

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/results

Responses

Status code

Returns the job's final result.

Status code

{
  "title": "ExternalResult",
  "type": "object",
  "description": "Result that points to an external URL to download the result from",
  "properties": {
    "url": {
      "type": "string",
      "description": "A URL to load the result from"
    }
  },
  "required": [
    "url"
  ]
}

List job interim results

Return the interim results from this job. Interim results are kept two days after the job has finished running.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	Returns job interim results.
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs/{id}/interim_results

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/interim_results

Responses

Status code

Returns job interim results.

Get job transpiled circuits

Return a presigned download URL for the transpiled circuits. Currently supported only for the circuit-runner primitive.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	Returns a presigned URL to download job transpiled circuits.
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs/{id}/transpiled_circuits

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/transpiled_circuits

Responses

Status code

Returns a presigned URL to download job transpiled circuits.

Status code

{
  "title": "JobsTranspiledCircuitsResponse",
  "type": "object",
  "description": "Jobs Transpiled Circuits presigned URL to download",
  "properties": {
    "url": {
      "description": "URL to download the transpiled circuits",
      "type": "string"
    }
  },
  "required": [
    "url"
  ]
}

List job logs

List all job logs for the specified job.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	Returns job logs.
401	Unauthorized
403	Forbidden
404	Not found

Code samples

GET

/jobs/{id}/logs

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/logs

Responses

Status code

Returns job logs.

Cancel a job

Cancels the specified job.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
204	OK
401	Unauthorized
403	Forbidden
404	Not Found
409	Job is in non cancellable status.

Code samples

POST

/jobs/{id}/cancel

curl -X POST -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/cancel

Responses

Status code

Get job metrics

Gets metrics of specified job

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/jobs/{id}/metrics

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/metrics

Responses

Status code

{
  "timestamps": {
    "created": "2022-06-20T12:55:20.268427Z",
    "running": "2022-06-20T12:55:20.268427Z",
    "finished": "2022-06-20T12:55:20.268427Z"
  },
  "bss": {
    "seconds": 123
  },
  "usage": {
    "quantum_seconds": 123,
    "seconds": 123
  },
  "executions": 123,
  "num_circuits": 123,
  "num_qubits": [
    1,
    2,
    3
  ],
  "circuit_depths": [
    0,
    1,
    2,
    3
  ],
  "qiskit_version": "0.36.2",
  "estimated_start_time": "2022-06-20T12:55:20.268427Z",
  "estimated_completion_time": "2022-06-20T12:55:20.268427Z",
  "position_in_queue": 10,
  "position_in_provider": 10
}

Status code

{
  "title": "JobMetrics",
  "type": "object",
  "description": "Various metrics about the execution of a job",
  "properties": {
    "timestamps": {
      "type": "object",
      "description": "A map of status transitions to timestamps",
      "properties": {
        "created": {
          "type": "string",
          "description": "Timestamp of when the job create request was received"
        },
        "finished": {
          "type": "string",
          "description": "Timestamp of when the job finished"
        },
        "running": {
          "type": "string",
          "description": "Timestamp of when the job started running"
        }
      }
    },
    "bss": {
      "type": "object",
      "description": "Contains information about job usage metrics",
      "properties": {
        "seconds": {
          "type": "integer",
          "description": "Total billed time for the job - quantum seconds only."
        }
      }
    },
    "usage": {
      "type": "object",
      "description": "Contains information about job usage metrics",
      "properties": {
        "quantum_seconds": {
          "type": "integer",
          "format": "int64",
          "description": "Total quantum seconds used by the job"
        },
        "seconds": {
          "type": "integer",
          "description": "Total billed time for the job - quantum seconds only."
        }
      }
    },
    "executions": {
      "type": "integer",
      "description": "Number of executions during job"
    },
    "num_circuits": {
      "type": "integer",
      "description": "Number of circuits executed on quantum backend"
    },
    "num_qubits": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Number of qubits on quantum backend"
    },
    "circuit_depths": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "An array of circuit depths"
    },
    "qiskit_version": {
      "type": "string",
      "description": "Qiskit version used during execution of the job"
    },
    "estimated_start_time": {
      "type": "string",
      "description": "UTC timestamp for when the job will start"
    },
    "estimated_completion_time": {
      "type": "string",
      "description": "UTC timestamp for when the job will complete"
    },
    "position_in_queue": {
      "type": "integer",
      "description": "Current position of job in queue"
    },
    "position_in_provider": {
      "type": "integer",
      "description": "Current position of job in provider"
    }
  }
}

Replace job tags

Path Parameters

Name, Type	Description
id Required string	A job ID

Body Parameters (application/json)

Name, Type	Description
Tags Required string[]	List of job or program tags

HTTP Response Status Codes

Status code	Description
204	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

PUT

/jobs/{id}/tags

curl -X PUT \
  -H "x-access-token: <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d {"tags":["tags","tags"]} \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/tags

Responses

Status code

Get the job results stream

Get a result stream as the job runs.

Path Parameters

Name, Type	Description
id Required string	A job ID

HTTP Response Status Codes

Status code	Description
200	WebSocket stream
303	Found
401	Unauthorized
500	Internal error

Code samples

GET

/stream/jobs/{id}

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/stream/jobs/{id}

Responses

Status code

WebSocket stream

Get jobs state updates

HTTP Response Status Codes

Status code	Description
200	WebSocket stream
303	Found
401	Unauthorized
500	Internal error

Code samples

GET

/stream/jobs

curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/stream/jobs

Responses

Status code

WebSocket stream