Skip to main contentIBM Quantum Documentation

Programs

Endpoints related to Qiskit Runtime programs

Add a program

Upload a new quantum program.

Body Parameters (application/json)

Name, TypeDescription
name
Required
string

Program name

cost
integer

Cost of the program as the estimated time it should take to complete (in seconds)

Default Value: 600
description
string

Program description to help others understand the purpose of this program

spec

Program information relevant to running this program

Tags
string[]

List of job or program tags

is_public
boolean

Indicates whether the program is public or private

Default Value: false
data
Required
string

The program text to upload, as a base64 encoded string

HTTP Response Status Codes

Status codeDescription
201Created
400Bad Request
401Unauthorized
403Forbidden

Code samples

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

Responses

{
  "id": "sample-program-abcdef123456",
  "name": "sample-program",
  "cost": 18000,
  "description": "A sample runtime program",
  "creation_date": "2021-05-10T08:59:51Z",
  "update_date": "2021-06-04T14:11:19Z",
  "spec": {
    "backend_requirements": {
      "min_num_qubits": 5
    },
    "parameters": {
      "properties": {
        "iterations": {
          "description": "Number of iterations to run. Each iteration generates and runs a random circuit.",
          "type": "integer",
          "minimum": 0
        }
      },
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "required": [
        "iterations"
      ]
    },
    "return_values": {
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "properties": {
        "result": {
          "description": "A string that says \"All done!\"",
          "type": "string"
        }
      }
    },
    "interim_results": {
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "properties": {
        "iteration": {
          "type": "integer",
          "description": "Iteration number"
        },
        "counts": {
          "type": "object",
          "description": "Histogram data of the circuit result"
        }
      }
    }
  },
  "is_public": true,
  "tags": [
    "tag1",
    "tag2",
    "tag3"
  ]
}

List programs

Returns a list of all programs you uploaded and all public programs.

Query Parameters

Name, TypeDescription
limit
integer

Number of results to return at a time

Default Value: 20
offset
integer

Number of results to offset when retrieving the list of jobs

Default Value: 0
name
string

Program name

search
string

Searches for programs containing the specified value in their name or description.

tags
string[]

List of job or program tags

HTTP Response Status Codes

Status codeDescription
200OK

Code samples

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

Responses

{
  "programs": [
    {
      "id": "sample-program-abcdef123456",
      "name": "sample-program",
      "cost": 18000,
      "description": "A sample runtime program",
      "creation_date": "2021-05-10T08:59:51Z",
      "update_date": "2021-06-04T14:11:19Z",
      "spec": {
        "backend_requirements": {
          "min_num_qubits": 5
        },
        "parameters": {
          "properties": {
            "iterations": {
              "description": "Number of iterations to run. Each iteration generates and runs a random circuit.",
              "type": "integer",
              "minimum": 0
            }
          },
          "$schema": "https://json-schema.org/draft/2019-09/schema",
          "required": [
            "iterations"
          ]
        },
        "return_values": {
          "$schema": "https://json-schema.org/draft/2019-09/schema",
          "properties": {
            "result": {
              "description": "A string that says \"All done!\"",
              "type": "string"
            }
          }
        },
        "interim_results": {
          "$schema": "https://json-schema.org/draft/2019-09/schema",
          "properties": {
            "iteration": {
              "type": "integer",
              "description": "Iteration number"
            },
            "counts": {
              "type": "object",
              "description": "Histogram data of the circuit result"
            }
          }
        }
      },
      "is_public": true,
      "tags": [
        "tag1",
        "tag2",
        "tag3"
      ],
      "summary": "A sample program response"
    }
  ],
  "count": 1,
  "limit": 1,
  "offset": 0
}

List program details

Return information about the specified program.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program

HTTP Response Status Codes

Status codeDescription
200OK
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

{
  "id": "sample-program-abcdef123456",
  "name": "sample-program",
  "cost": 18000,
  "description": "A sample runtime program",
  "creation_date": "2021-05-10T08:59:51Z",
  "update_date": "2021-06-04T14:11:19Z",
  "spec": {
    "backend_requirements": {
      "min_num_qubits": 5
    },
    "parameters": {
      "properties": {
        "iterations": {
          "description": "Number of iterations to run. Each iteration generates and runs a random circuit.",
          "type": "integer",
          "minimum": 0
        }
      },
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "required": [
        "iterations"
      ]
    },
    "return_values": {
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "properties": {
        "result": {
          "description": "A string that says \"All done!\"",
          "type": "string"
        }
      }
    },
    "interim_results": {
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "properties": {
        "iteration": {
          "type": "integer",
          "description": "Iteration number"
        },
        "counts": {
          "type": "object",
          "description": "Histogram data of the circuit result"
        }
      }
    }
  },
  "is_public": true,
  "tags": [
    "tag1",
    "tag2",
    "tag3"
  ]
}

Delete a program

Delete the specified program.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

OK

Update program metadata

Update the name, cost, description, or add more backend requirements, parameters, return values, and results. To update the actual program data, use the PUT endpoint instead.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program

Body Parameters (application/json)

Name, TypeDescription
name
string

Program name

cost
integer

Cost of the program as the estimated time it should take to complete (in seconds)

Default Value: 600
description
string

Program description to help others understand the purpose of this program

spec

Program information relevant to running this program

Tags
string[]

List of job or program tags

HTTP Response Status Codes

Status codeDescription
204OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

OK

Update a program

Update the program data for the specified program. To update or add metadata, use the Patch endpoint instead.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program.

Body Parameters (application/octet-stream)

Name, TypeDescription
object

Program data as a base64 encoded string

HTTP Response Status Codes

Status codeDescription
204OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

OK

Make a program public

Make a program that you uploaded publicly available. Others will be able to view and run the program, but only you will be able to edit it.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

OK

Make a program private

You can only make a program private if you uploaded it.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an available program

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

OK
Was this page helpful?