Skip to main content
IBM Quantum Platform
This REST API is only available to On-Prem Plan members who have enabled it in their environment.

Jobs

Run a job

Invoke a Qiskit Runtime primitive.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

  • quantum-computing.direct-access-job.create

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.direct-access-job.create

Input

Body Parameters
Name, Type
Description
backend
Required
string

Name of the backend

Example: "ibm_rensselaer"
id
Required
string

Job identifier. Recommended to be UUID

log_level
string

Logging level of the program

Possible values: infodebugwarningerrorcritical
Default value: warning
program_id
Required
string

ID of the program

Example: "sampler"
storage
Required
timeout_secs
Required
integer

Time (in seconds) after which job should time out and get cancelled. It is based on system execution time (not wall clock time). System execution time is the amount of time that the system is dedicated to processing your job.

Code samples
POST
/v1/jobs
curl -X POST \
  'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"id":"example","program_id":"sampler","backend":"ibm_rensselaer","timeout_secs":1,"storage":{}}'

Output

HTTP Response Status Codes
Status code
Description
204Returned when job was submitted successfully.
400Returned when invalid input is received.
401Returned when authentication failed.
404Returned when the backend was not found
408Returned when the request took too long to read.
409Returned when a duplicate job with same job ID was submitted.
413Returned when the request body is too large.
422Returned when validation of the request failed. The error message contains details about the specific validation error.
423The requested backend is reserved and jobs outside of the reservation cannot be run.
429Returned when per backend concurrent job limit has been reached. Try again later once existing jobs terminate and delete terminated jobs to submit more.
Responses
Returned when job was submitted successfully.

Get jobs

Fetches a list of all jobs submitted by the current authenticated client, ordered by creation time in ascending order.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

  • quantum-computing.direct-access-job.list

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.direct-access-job.list

Input

Infomation
This endpoint accepts no inputs.
Code samples
GET
/v1/jobs
curl -X GET \
  'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs' \
  -H 'Accept: application/json'

Output

HTTP Response Status Codes
Status code
Description
200Returned when jobs were retrieved successfully.
401Returned when authentication failed.
Responses
{
  "jobs": [
    {
      "backend": "ibm_rensselaer",
      "created_time": "example",
      "end_time": "example",
      "id": "example",
      "log_level": "info",
      "program_id": "sampler",
      "reason_code": 1,
      "reason_message": "example",
      "reason_solution": "example",
      "status": "Running",
      "storage": {
        "input": {
          "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
          "object_name": "example",
          "presigned_url": "example",
          "region": "us-east",
          "region_type": "regional",
          "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
          "type": "s3_compatible"
        },
        "logs": {
          "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
          "object_name": "example",
          "presigned_url": "example",
          "region": "us-east",
          "region_type": "regional",
          "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
          "type": "s3_compatible"
        },
        "results": {
          "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
          "object_name": "example",
          "presigned_url": "example",
          "region": "us-east",
          "region_type": "regional",
          "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
          "type": "s3_compatible"
        }
      },
      "timeout_secs": 1,
      "usage": {
        "quantum_nanoseconds": 1
      }
    }
  ]
}

Get Job by ID

Fetches a single job by its unique identifier for the current authenticated client.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

  • quantum-computing.direct-access-job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.direct-access-job.read

Input

Path Parameters
Name, Type
Description
job-id
Required
string
Code samples
GET
/v1/jobs/{job-id}
curl -X GET \
  'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs/{job-id}' \
  -H 'Accept: application/json'

Output

HTTP Response Status Codes
Status code
Description
200Job retrieved successfully.
401Returned when authentication failed.
404No job found for the provided ID belonging to the authenticated client.
Responses
{
  "backend": "ibm_rensselaer",
  "created_time": "example",
  "end_time": "example",
  "id": "example",
  "log_level": "info",
  "program_id": "sampler",
  "reason_code": 1,
  "reason_message": "example",
  "reason_solution": "example",
  "status": "Running",
  "storage": {
    "input": {
      "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
      "object_name": "example",
      "presigned_url": "example",
      "region": "us-east",
      "region_type": "regional",
      "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
      "type": "s3_compatible"
    },
    "logs": {
      "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
      "object_name": "example",
      "presigned_url": "example",
      "region": "us-east",
      "region_type": "regional",
      "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
      "type": "s3_compatible"
    },
    "results": {
      "bucket_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/abc123:abc123:bucket:my-bucket",
      "object_name": "example",
      "presigned_url": "example",
      "region": "us-east",
      "region_type": "regional",
      "runtime_instance_crn": "crn:v1:bluemix:public:quantum-computing:us-east:a/abc123:abc123::",
      "type": "s3_compatible"
    }
  },
  "timeout_secs": 1,
  "usage": {
    "quantum_nanoseconds": 1
  }
}

Delete a job

Deletes a job if it has terminated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

  • quantum-computing.direct-access-job.delete

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.direct-access-job.delete

Input

Path Parameters
Name, Type
Description
job-id
Required
string
Code samples
DELETE
/v1/jobs/{job-id}
curl -X DELETE \
  'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs/{job-id}' \
  -H 'Accept: application/json'

Output

HTTP Response Status Codes
Status code
Description
204Returned when job was deleted successfully.
401Returned when authentication failed.
404Returned when job is not found.
409Returned when a job has not yet terminated and has to be cancelled before it can be deleted.
Responses
Returned when job was deleted successfully.

Cancel a job

Cancels a job if it has not yet terminated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

  • quantum-computing.direct-access-job.cancel

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.direct-access-job.cancel

Input

Path Parameters
Name, Type
Description
job-id
Required
string
Code samples
POST
/v1/jobs/{job-id}/cancel
curl -X POST \
  'https://direct-access-<YOUR_CLIENT_ACRONYM>.quantum-computing.cloud.ibm.com:30060/v1/jobs/{job-id}/cancel' \
  -H 'Accept: application/json'

Output

HTTP Response Status Codes
Status code
Description
204Returned when job cancel request was submitted successfully.
401Returned when authentication failed.
404Returned when job is not found.
409Returned when a job has already terminated and cannot be cancelled.
500Returned when an internal server error occurs.
Responses
Returned when job cancel request was submitted successfully.
Was this page helpful?
Report a bug, typo, or request content on GitHub.