Jobs
Gets metrics of specified job
Get job metrics as an admin
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Various metrics about the execution of a job |
401 | Unauthorized |
403 | Forbidden |
404 | Not found |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/admin/jobs/{id}/metrics \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/admin/jobs/{id}/metrics",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"bss": {
"seconds": 1
},
"usage": {
"quantum_seconds": 10,
"seconds": 10
},
"timestamps": {
"created": "2022-06-20T12:55:20.268427Z",
"finished": "2022-06-20T12:55:20.268427Z",
"running": "2022-06-20T12:55:20.268427Z"
},
"executions": 10,
"num_circuits": 10,
"num_qubits": [
1,
2,
3
],
"circuit_depths": [
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
}
{
"type": "object",
"properties": {
"bss": {
"example": {
"seconds": 1
},
"description": "Contains information about billing metrics",
"allOf": [
{
"type": "object",
"properties": {
"seconds": {
"type": "number",
"example": 10,
"description": "Total billed time for the job - quantum seconds only."
}
}
}
]
},
"usage": {
"example": {
"quantum_seconds": 10,
"seconds": 10
},
"description": "Contains information about job usage metrics",
"allOf": [
{
"type": "object",
"properties": {
"quantum_seconds": {
"type": "number",
"example": 10,
"format": "int64",
"description": "Total quantum seconds used by the instance"
},
"seconds": {
"type": "number",
"example": 10,
"description": "Total billed time for the job - quantum seconds only."
}
}
}
]
},
"timestamps": {
"example": {
"created": "2022-06-20T12:55:20.268427Z",
"finished": "2022-06-20T12:55:20.268427Z",
"running": "2022-06-20T12:55:20.268427Z"
},
"description": "A map of status transitions to timestamps",
"allOf": [
{
"type": "object",
"properties": {
"created": {
"type": "string",
"example": "2022-06-20T12:55:20.268427Z",
"description": "Timestamp of when the job create request was received"
},
"finished": {
"type": "string",
"example": "2022-06-20T12:55:20.268427Z",
"description": "Timestamp of when the job finished"
},
"running": {
"type": "string",
"example": "2022-06-20T12:55:20.268427Z",
"description": "Timestamp of when the job started running"
}
}
}
]
},
"executions": {
"type": "number",
"example": 10,
"description": "Number of executions during job"
},
"num_circuits": {
"type": "number",
"example": 10,
"description": "Number of circuits executed on quantum backend"
},
"num_qubits": {
"example": [
1,
2,
3
],
"description": "Number of qubits on quantum backend",
"type": "array",
"items": {
"type": "string"
}
},
"circuit_depths": {
"example": [
1,
2,
3
],
"description": "An array of circuit depths",
"type": "array",
"items": {
"type": "string"
}
},
"qiskit_version": {
"type": "string",
"example": "0.36.2",
"description": "Qiskit version used during execution of the job"
},
"estimated_start_time": {
"type": "string",
"example": "2022-06-20T12:55:20.268427Z",
"description": "UTC timestamp for when the job will start"
},
"estimated_completion_time": {
"type": "string",
"example": "2022-06-20T12:55:20.268427Z",
"description": "UTC timestamp for when the job will complete"
},
"position_in_queue": {
"type": "number",
"example": 10,
"description": "Current position of job in queue"
},
"position_in_provider": {
"type": "number",
"example": 10,
"description": "Current position of job in provider"
}
},
"required": [
"timestamps"
]
}
List user jobs
List user jobs
Query Parameters
Name, Type | Description |
---|---|
provider string | Instance to filter jobs. Should be in the following format {hub}/{group}/{project} |
pending boolean | Filters only pending or non pending jobs |
backend string | Comma separated systems to filter jobs |
sort string | Sort jobs by created time Possible values: ASC DESC Default value: DESC |
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 |
createdAfter string | Job created after filter |
createdBefore string | Job created before filter |
tags string[] | Tags to filter jobs |
program string | Program ID to filter jobs |
sessionId string | Session ID to filter jobs |
composerOnly boolean | Returns composer jobs only Default value: false |
composerFile string | Composer file name to filter jobs |
search string | Searches for jobs containing the specified keyword in their id, name or tags |
HTTP Response Status Codes
Status code | Description |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"jobs": [
{
"id": "c5dge2d3rn7breq27i9g",
"hub": "ibm-q",
"group": "open",
"project": "main",
"backend": "ibm_brisbane",
"status": "Completed",
"created": "2021-10-04T13:52:09.456851Z",
"type": "RUNTIME",
"tags": [
"tag1",
"tag2"
],
"name": "",
"runMode": "",
"private": false,
"endTime": "2021-10-04T13:54:09.456851Z",
"state": {
"status": "Completed",
"reason": ""
},
"program": {
"id": "myprogram-abcdef12345"
},
"runtime": "ntc-provider-primitives:latest",
"sessionId": "123"
}
],
"count": 1,
"limit": 1,
"offset": 0
}
{
"title": "UserJobsResponse",
"description": "Jobs collection response",
"allOf": [
{
"type": "object",
"title": "PaginationInfo",
"description": "Pagination info",
"properties": {
"count": {
"type": "integer",
"description": "Total number of results"
},
"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": [
"count",
"offset",
"limit"
]
},
{
"type": "object",
"properties": {
"jobs": {
"description": "A list of jobs",
"type": "array",
"items": {
"title": "UserJobResponse",
"allOf": [
{
"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 of the instance in which the job is being executed"
},
"group": {
"type": "string",
"description": "Name of the group of the instance in which the job is being executed"
},
"project": {
"type": "string",
"description": "Name of the project of the instance in which the job is being executed"
},
"backend": {
"type": "string",
"description": "The system on which to run the program. If no system is specified, the job is sent to the system with the shortest queue that you have access to.",
"pattern": ".*"
},
"status": {
"type": "string",
"description": "Current status of the job",
"enum": [
"CREATING",
"CREATED",
"ERROR_CREATING_JOB",
"VALIDATING",
"VALIDATED",
"ERROR_VALIDATING_JOB",
"TRANSPILING",
"TRANSPILED",
"ERROR_TRANSPILING_JOB",
"QUEUED",
"Queued",
"RUNNING",
"Running",
"COMPLETED",
"Completed",
"ERROR_RUNNING_JOB",
"CANCELLED",
"Cancelled",
"FAILED",
"Failed"
]
},
"created": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp for when the job was created"
},
"type": {
"type": "string",
"description": "Job type",
"enum": [
"IQX",
"RUNTIME"
]
},
"tags": {
"type": "array",
"description": "Tags associated with the job",
"items": {
"type": "string"
}
},
"name": {
"type": "string",
"description": "Job name"
},
"runMode": {
"type": "string",
"description": "Job run mode",
"enum": [
"fairshare",
"dedicated",
"priority",
"session"
]
},
"private": {
"type": "boolean",
"description": "Job ran in private mode"
},
"endTime": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp for when the job finished running"
},
"estimated_running_time_seconds": {
"type": "number",
"format": "double",
"description": "estimated running time of the job"
},
"estimated_max_running_time_seconds": {
"type": "number",
"format": "double",
"description": "estimated max running time of the job"
}
},
"required": [
"id",
"hub",
"group",
"project",
"backend",
"status",
"created",
"type",
"tags",
"name",
"runMode",
"private"
]
},
{
"type": "object",
"properties": {
"program": {
"title": "Program",
"type": "object",
"description": "A program",
"properties": {
"id": {
"type": "string",
"description": "Program ID"
}
},
"required": [
"id"
]
},
"runtime": {
"type": "string",
"description": "Name and tag of the image to use when running a program"
},
"sessionId": {
"type": "string",
"description": "Identifier of the session that the job is a part of"
},
"state": {
"title": "JobState",
"type": "object",
"description": "Current state of the job",
"properties": {
"status": {
"type": "string",
"description": "Current status of the job",
"enum": [
"CREATING",
"CREATED",
"ERROR_CREATING_JOB",
"VALIDATING",
"VALIDATED",
"ERROR_VALIDATING_JOB",
"TRANSPILING",
"TRANSPILED",
"ERROR_TRANSPILING_JOB",
"QUEUED",
"Queued",
"RUNNING",
"Running",
"COMPLETED",
"Completed",
"ERROR_RUNNING_JOB",
"CANCELLED",
"Cancelled",
"FAILED",
"Failed"
]
},
"reason": {
"type": "string",
"description": "Reason for the current status"
},
"reason_code": {
"type": "integer",
"description": "Reason code for the current status"
}
},
"required": [
"status",
"reason"
]
}
},
"required": [
"runtime",
"sessionId",
"state"
]
}
]
}
}
},
"required": [
"jobs"
]
}
]
}
List tags
List tags containing the search keyword from all the user jobs
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/tags \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/tags",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"tags": [
"tag1",
"tag2",
"tag3"
],
"count": 3,
"limit": 10,
"offset": 0
}
{
"title": "TagsResponse",
"allOf": [
{
"type": "object",
"title": "PaginationInfo",
"description": "Pagination info",
"properties": {
"count": {
"type": "integer",
"description": "Total number of results"
},
"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": [
"count",
"offset",
"limit"
]
},
{
"type": "object",
"properties": {
"tags": {
"type": "array",
"title": "Tags",
"description": "Tags sorted ASC",
"items": {
"type": "string"
}
}
},
"required": [
"tags"
]
}
]
}
Get job type
Get job type
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/{jobId}/type \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/{jobId}/type",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"id": "c5dge2d3rn7breq27i9g",
"type": "RUNTIME"
}
{
"title": "JobTypeResponse",
"type": "object",
"description": "Job type response",
"properties": {
"id": {
"type": "string",
"description": "Identifier assigned to the job"
},
"type": {
"type": "string",
"description": "Job type",
"enum": [
"IQX",
"RUNTIME"
]
}
},
"required": [
"id",
"type"
]
}
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.
Body Parameters (application/json)
Name, Type | Description |
---|---|
program_id Required string | ID of the primitive to be executed Example: "sampler" |
hub Required string | The hub of the instance Example: "ibm-q" |
group Required string | The group of the instance Example: "open" |
project Required string | The project of the instance Example: "main" |
backend Required string | Name that identifies the system on which to run the job Example: "ibm_sherbrooke" |
params | Parameters to inject into the primitive as key-value pairs Example: {"pubs":[["OPENQASM 3.0; include \\\"stdgates.inc\\\"; bit[2] meas; rz(pi/2) $0; sx $0; rz(pi/2) $0; cx $0, $1; meas[0] = measure $0; meas[1] = measure $1;",[],128]],"supports_qiskit":false,"version":2} |
log_level string | Logging level of the job Possible values: critical error warning info debug Example: "info" |
session_id string | Identifier of the session that the job is a part of Example: "example_session_id" |
tags string[] | List of job tags Example: ["job-1"] |
cost number | Cost of the job as the estimated time it should take to complete (in seconds). Should not exceed the cost of the primitive Example: 450 |
private boolean | Indicates if job to create will be private or not |
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Returns the created job |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
409 | Conflict |
500 | Internal server error |
Code samples
curl -X POST \
https://api.quantum-computing.ibm.com/runtime/jobs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"program_id":"sampler","hub":"ibm-q","group":"open","project":"main","backend":"ibm_sherbrooke"}'
import requests
response = requests.request(
"POST",
"https://api.quantum-computing.ibm.com/runtime/jobs",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
data="{\"program_id\":\"sampler\",\"hub\":\"ibm-q\",\"group\":\"open\",\"project\":\"main\",\"backend\":\"ibm_sherbrooke\"}"
)
print(response.json())
Responses
{
"id": "ci8fo2g4mgo3p0c53uc0",
"backend": "ibmq_toronto",
"session_id": "ci8fo2g4mgo3p0c53uc0",
"messages": [
{
"level": "warn",
"data": "Your current pending jobs are estimated to consume 200 quantum seconds, but you only have 100 quantum seconds left in your monthly quota; therefore, it is likely this job will be canceled"
}
]
}
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ci8fo2g4mgo3p0c53uc0"
},
"backend": {
"type": "string",
"example": "ibmq_toronto"
},
"session_id": {
"type": "string",
"example": "ci8fo2g4mgo3p0c53uc0"
},
"messages": {
"example": [
{
"level": "warn",
"data": "Your current pending jobs are estimated to consume 200 quantum seconds, but you only have 100 quantum seconds left in your monthly quota; therefore, it is likely this job will be canceled"
}
],
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"backend",
"session_id",
"messages"
]
}
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 | Instance to filter jobs. Should be in the following format {hub}/{group}/{project} |
program string | Program ID to filter jobs |
backend string | System 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[] | Tags to filter jobs |
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
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"jobs": [
{
"id": "c5dge2d3rn7breq27i9g",
"backend": "ibm_brisbane",
"state": {
"status": "Completed",
"reason": ""
},
"status": "Completed",
"params": {
"iterations": 3
},
"program": {
"id": "sampler"
},
"created": "2021-10-04T13:52:09.456851Z",
"ended": "2021-10-04T13:58:09.456851Z",
"runtime": "ntc-provider-primitives:latest",
"tags": [
"tag1",
"tag2",
"tag3",
"tag4"
],
"session_id": "c5dge2d3rn7breq27i9g",
"user_id": "66b151c0456fa30442933700",
"usage": {
"seconds": 1
}
}
],
"count": 1,
"limit": 1,
"offset": 0
}
{
"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 of the instance in which the job is being executed"
},
"group": {
"type": "string",
"description": "Name of the group of the instance in which the job is being executed"
},
"project": {
"type": "string",
"description": "Name of the project of the instance in which the job is being executed"
},
"backend": {
"type": "string",
"description": "The system on which to run the job. If no system is specified, the job is sent to the system 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"
},
"ended": {
"type": "string",
"description": "UTC timestamp for when the job has ended"
},
"runtime": {
"type": "string",
"description": "Name and tag of the image to use when running a program"
},
"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)"
},
"user_id": {
"type": "string",
"description": "User identifier from the job owner"
}
},
"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"
]
}
Get job
Get the details about the specified quantum job
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Returns the job details |
401 | Unauthorized |
404 | Not found |
500 | Internal server error |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id} \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"id": "ch8b1ok4k9li68vm059r",
"hub": "ibmq",
"group": "open",
"project": "main",
"backend": "ibm_seattle",
"state": {
"status": "Cancelled",
"reason": "Ran too long",
"reason_code": 1234
},
"status": "Completed",
"params": {},
"program": {
"id": "ch8b1ok4k9li68vm059r"
},
"created": "2021-05-05 00:56:04.569709",
"ended": "2021-05-05 00:56:04.569709",
"runtime": "example",
"cost": 1,
"tags": [
"test-job"
],
"session_id": "ch8b1ok4k9li68vm059r",
"usage": {
"seconds": 1
},
"estimated_running_time_seconds": 123,
"estimated_max_running_time_seconds": 123,
"private": true,
"user_id": "66b151c0456fa30442933700"
}
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ch8b1ok4k9li68vm059r"
},
"hub": {
"type": "string",
"example": "ibmq"
},
"group": {
"type": "string",
"example": "open"
},
"project": {
"type": "string",
"example": "main"
},
"backend": {
"type": "string",
"example": "ibm_seattle"
},
"state": {
"example": {
"status": "Cancelled",
"reason": "Ran too long",
"reason_code": 1234
},
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "Cancelled",
"enum": [
"Completed",
"Cancelled",
"Failed",
"Queued",
"Running"
]
},
"reason": {
"type": "string",
"example": "Ran too long"
},
"reason_code": {
"type": "number",
"example": 1010
}
},
"required": [
"status"
]
}
]
},
"status": {
"type": "string",
"description": "Job status, if cancelled, the reason is included in the status field like \"Cancelled - Ran too long\"",
"example": "Completed",
"enum": [
"Completed",
"Cancelled",
"Failed",
"Queued",
"Running"
]
},
"params": {
"type": "object",
"example": {}
},
"program": {
"type": "object",
"example": {
"id": "ch8b1ok4k9li68vm059r"
}
},
"created": {
"format": "date-time",
"type": "string",
"example": "2021-05-05 00:56:04.569709"
},
"ended": {
"format": "date-time",
"type": "string",
"example": "2021-05-05 00:56:04.569709"
},
"runtime": {
"type": "string"
},
"cost": {
"type": "number",
"example": 0
},
"tags": {
"example": [
"test-job"
],
"type": "array",
"items": {
"type": "string"
}
},
"session_id": {
"type": "string",
"example": "ch8b1ok4k9li68vm059r"
},
"usage": {
"type": "object",
"example": {
"seconds": 1
}
},
"estimated_running_time_seconds": {
"type": "number",
"example": 123
},
"estimated_max_running_time_seconds": {
"type": "number",
"example": 123
},
"private": {
"type": "boolean",
"example": false
},
"user_id": {
"type": "string",
"example": "66b151c0456fa30442933700"
}
},
"required": [
"id",
"hub",
"group",
"project",
"backend",
"state",
"status",
"params",
"program",
"created",
"ended",
"runtime",
"cost",
"tags",
"session_id",
"usage",
"estimated_running_time_seconds",
"estimated_max_running_time_seconds",
"private",
"user_id"
]
}
Delete a job
Delete the specified job.
Code samples
curl -X DELETE \
https://api.quantum-computing.ibm.com/runtime/jobs/{id} \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"DELETE",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
Cancel a job
Cancels the specified job.
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
curl -X POST \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/cancel \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"POST",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/cancel",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
List job interim results
Return the interim results from this job. Interim results are kept two days after the job has finished running.
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Returns job interim results. |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/interim_results \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/interim_results",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
List job logs
List all job logs for the specified job.
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Returns job logs. |
401 | Unauthorized |
403 | Forbidden |
404 | Not found |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/logs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/logs",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
Get job metrics
Gets metrics of specified job
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/metrics \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/metrics",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"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
}
{
"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 system"
},
"num_qubits": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Number of qubits on quantum system"
},
"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 instance"
}
}
}
Get job results
Return the final result from this job.
HTTP Response Status Codes
Status code | Description |
---|---|
200 | Return the job results |
204 | The job exists but there is no result |
401 | Unauthorized |
404 | Not found |
500 | Internal server error |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/results \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/results",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"oneOf": [
{
"title": "Sampler V2 Job Result",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://www.qiskit.org/schemas/sampler_result_v2_schema.json",
"description": "The result for an SamplerV2 API call",
"version": "1.0.0",
"type": "object",
"required": [
"results",
"metadata"
],
"properties": {
"results": {
"type": "array",
"description": "Array of results, one for each PUB in the original job",
"items": {
"type": "object",
"description": "A single PUB result, containing result data and metadata",
"required": [
"data",
"metadata"
],
"properties": {
"data": {
"type": "object",
"description": "PUB results for sampler are split according to the classical bits register names. For each register, an array of samples (in hexadecimal string format) is returned",
"additionalProperties": {
"type": "object",
"description": "The data corresponding to a specific measurement",
"properties": {
"samples": {
"type": "array",
"description": "An array of samples (given as hexadecimal strings)",
"items": {
"type": "string"
}
},
"num_bits": {
"type": "integer",
"description": "The number of measured bits"
}
}
}
},
"metadata": {
"type": "object",
"description": "PUB-specific metadata"
}
}
}
},
"metadata": {
"type": "object",
"description": "Metadata for the job"
}
}
},
{
"title": "Estimator V2 Job Result",
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://www.qiskit.org/schemas/estimator_result_v2_schema.json",
"description": "The result for an EstimatorV2 API call",
"version": "1.0.0",
"type": "object",
"required": [
"results",
"metadata"
],
"properties": {
"results": {
"type": "array",
"description": "Array of results, one for each PUB in the original job",
"items": {
"type": "object",
"description": "A single PUB result, containing result data and metadata",
"required": [
"data",
"metadata"
],
"properties": {
"data": {
"type": "object",
"description": "PUB results for estimator include expectation values and standard errors, which can be either numbers or multidimensional arrays of numbers, depending on the shape of the observables and parameters in the original PUB",
"required": [
"evs",
"stds"
],
"properties": {
"evs": {
"anyOf": [
{
"type": "number"
},
{
"type": "array"
}
]
},
"stds": {
"anyOf": [
{
"type": "number"
},
{
"type": "array"
}
]
},
"ensamble_standard_error": {
"anyOf": [
{
"type": "number"
},
{
"type": "array"
}
]
}
}
},
"metadata": {
"type": "object",
"description": "PUB-specific metadata"
}
}
}
},
"metadata": {
"type": "object",
"description": "Metadata for the job"
}
}
}
]
}
Replace job tags
Replace job tags
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
curl -X PUT \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/tags \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"tags":["example"]}'
import requests
response = requests.request(
"PUT",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/tags",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
data="{\"tags\":[\"example\"]}"
)
print(response.json())
Responses
Get job transpiled circuits
Return a presigned download URL for the transpiled circuits. Currently supported only for the sampler primitive.
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
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/jobs/{id}/transpiled_circuits \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/jobs/{id}/transpiled_circuits",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
{
"url": "https://quantum.ibm.com/transpiled-circuit/url"
}
{
"title": "JobsTranspiledCircuitsResponse",
"type": "object",
"description": "Jobs Transpiled Circuits presigned URL to download",
"properties": {
"url": {
"description": "URL to download the transpiled circuits",
"type": "string",
"example": "https://quantum.ibm.com/transpiled-circuit/url"
}
},
"required": [
"url"
]
}
Get jobs state updates
Get jobs state updates
HTTP Response Status Codes
Status code | Description |
---|---|
200 | WebSocket stream |
303 | Found |
401 | Unauthorized |
500 | Internal error |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/stream/jobs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/stream/jobs",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())
Responses
Get the job results stream
Get a result stream as the job runs.
HTTP Response Status Codes
Status code | Description |
---|---|
200 | WebSocket stream |
303 | Found |
401 | Unauthorized |
500 | Internal error |
Code samples
curl -X GET \
https://api.quantum-computing.ibm.com/runtime/stream/jobs/{id} \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'
import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/stream/jobs/{id}",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())