AI Routing methods

Get available backends

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

GET

/routing/backends

curl -X GET \
  https://cloud-transpiler.quantum.ibm.com/routing/backends \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

import requests
 
response = requests.request(
    "GET",
    "https://cloud-transpiler.quantum.ibm.com/routing/backends",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
)
print(response.json())

Responses

Status code

[
  "example"
]

Status code

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "title": "Response Backends Routing Backends Get"
}

Benchmark AI-powered routing

Returns a task ID; use the '/routing/benchmark/{taskId}' endpoint to get the result.

Query Parameters

Name, Type	Description
optimization_level integer	Default value: `1`
layout_mode string	Possible values: `keepoptimizeimprove` Default value: `keep`

Body Parameters (application/json)

Name, Type Description

Name, Type	Description
qasm Required string	The OpenQASM circuit to route. Both OpenQASM 2 and OpenQASM 3 are supported. Example: `"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];"` Example: `"OPENQASM 2.0;\ninclude \"qelib1.inc\";\ngate dcx q0,q1 { cx q0,q1; cx q1,q0; }\nqreg q[3];\ncz q[0],q[2];\nsdg q[1];\ndcx q[2],q[1];\nu3(3.890139082217223,3.447697582994976,1.1583481971959322) q[0];\ncrx(2.3585459177723522) q[1],q[0];\ny q[2];"`
coupling_map Required integer[][] \| string	Example: `[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]` Example: `"ibm_sherbrooke"`

qasm

Required

string

The OpenQASM circuit to route. Both OpenQASM 2 and OpenQASM 3 are supported.

Example:

"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];"

Example:

"OPENQASM 2.0;\ninclude \"qelib1.inc\";\ngate dcx q0,q1 { cx q0,q1; cx q1,q0; }\nqreg q[3];\ncz q[0],q[2];\nsdg q[1];\ndcx q[2],q[1];\nu3(3.890139082217223,3.447697582994976,1.1583481971959322) q[0];\ncrx(2.3585459177723522) q[1],q[0];\ny q[2];"

coupling_map

Required

integer[][] | string

Example: [[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]

Example: "ibm_sherbrooke"

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

POST

/routing/benchmark

curl -X POST \
  https://cloud-transpiler.quantum.ibm.com/routing/benchmark \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"qasm":"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];","coupling_map":[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]}'

import requests
 
response = requests.request(
    "POST",
    "https://cloud-transpiler.quantum.ibm.com/routing/benchmark",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
    data="{\"qasm\":\"OPENQASM 3; include \\\"stdgates.inc\\\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];\",\"coupling_map\":[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]}"
)
print(response.json())

Responses

Status code

{
  "task_id": "example"
}

Status code

{
  "properties": {
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  },
  "type": "object",
  "required": [
    "task_id"
  ],
  "title": "TaskIdResponse"
}

Get benchmark result

Path Parameters

Name, Type	Description
task_id Required string	The ID of the benchmark task. This ID is returned by the '/routing/benchmark' POST endpoint.

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

GET

/routing/benchmark/{task_id}

curl -X GET \
  https://cloud-transpiler.quantum.ibm.com/routing/benchmark/{task_id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

import requests
 
response = requests.request(
    "GET",
    "https://cloud-transpiler.quantum.ibm.com/routing/benchmark/{task_id}",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
)
print(response.json())

Responses

Status code

{
  "state": "example",
  "result": null
}

Status code

{
  "properties": {
    "state": {
      "type": "string",
      "title": "State"
    },
    "result": {
      "anyOf": [
        {
          "items": {
            "properties": {
              "algorithm_name": {
                "type": "string",
                "title": "Algorithm Name"
              },
              "algorithm_name_compact": {
                "type": "string",
                "title": "Algorithm Name Compact"
              },
              "qasm": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Qasm"
              },
              "success": {
                "type": "boolean",
                "title": "Success"
              },
              "metrics": {
                "anyOf": [
                  {
                    "properties": {
                      "n_gates": {
                        "type": "integer",
                        "title": "N Gates"
                      },
                      "n_layers": {
                        "type": "integer",
                        "title": "N Layers"
                      },
                      "n_cnots": {
                        "type": "integer",
                        "title": "N Cnots"
                      },
                      "n_layers_cnots": {
                        "type": "integer",
                        "title": "N Layers Cnots"
                      },
                      "synthesize_time": {
                        "anyOf": [
                          {
                            "type": "number"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "title": "Synthesize Time"
                      }
                    },
                    "type": "object",
                    "required": [
                      "n_gates",
                      "n_layers",
                      "n_cnots",
                      "n_layers_cnots"
                    ],
                    "title": "BaseMetrics"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "type": "object",
            "required": [
              "algorithm_name",
              "algorithm_name_compact",
              "success"
            ],
            "title": "BenchmarkResult"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Result"
    }
  },
  "type": "object",
  "required": [
    "state"
  ],
  "title": "TaskBenchmarkResultResponse"
}

Route circuit to coupling map

Returns a task ID; use the '/routing/routing/{taskId}' endpoint to get the result.

Query Parameters

Name, Type	Description
check_result boolean	If true, the RL model will check the result before returning a response Default value: `false`
optimization_level integer	How much to optimize the circuit. Refer to https://docs.quantum.ibm.com/transpile/ai-transpiler-passes#ai-routing-pass Default value: `2`
layout_mode string	Possible values: `keepoptimizeimprove` Default value: `keep`

Body Parameters (application/json)

Name, Type Description

Name, Type	Description
qasm Required string	The OpenQASM circuit to route. Both OpenQASM 2 and OpenQASM 3 are supported. Example: `"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];"` Example: `"OPENQASM 2.0;\ninclude \"qelib1.inc\";\ngate dcx q0,q1 { cx q0,q1; cx q1,q0; }\nqreg q[3];\ncz q[0],q[2];\nsdg q[1];\ndcx q[2],q[1];\nu3(3.890139082217223,3.447697582994976,1.1583481971959322) q[0];\ncrx(2.3585459177723522) q[1],q[0];\ny q[2];"`
coupling_map Required integer[][] \| string	Example: `[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]` Example: `"ibm_sherbrooke"`

qasm

Required

string

The OpenQASM circuit to route. Both OpenQASM 2 and OpenQASM 3 are supported.

Example:

"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];"

Example:

"OPENQASM 2.0;\ninclude \"qelib1.inc\";\ngate dcx q0,q1 { cx q0,q1; cx q1,q0; }\nqreg q[3];\ncz q[0],q[2];\nsdg q[1];\ndcx q[2],q[1];\nu3(3.890139082217223,3.447697582994976,1.1583481971959322) q[0];\ncrx(2.3585459177723522) q[1],q[0];\ny q[2];"

coupling_map

Required

integer[][] | string

Example: [[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]

Example: "ibm_sherbrooke"

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

POST

/routing/routing

curl -X POST \
  https://cloud-transpiler.quantum.ibm.com/routing/routing \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"qasm":"OPENQASM 3; include \"stdgates.inc\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];","coupling_map":[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]}'

import requests
 
response = requests.request(
    "POST",
    "https://cloud-transpiler.quantum.ibm.com/routing/routing",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
    data="{\"qasm\":\"OPENQASM 3; include \\\"stdgates.inc\\\"; bit[2] meas; qubit[2] q; h q[0]; cx q[0], q[1]; barrier q[0], q[1]; meas[0] = measure q[0]; meas[1] = measure q[1];\",\"coupling_map\":[[0,1],[1,2],[2,3],[3,4],[4,5],[5,6],[6,7]]}"
)
print(response.json())

Responses

Status code

{
  "task_id": "example"
}

Status code

{
  "properties": {
    "task_id": {
      "type": "string",
      "title": "Task Id"
    }
  },
  "type": "object",
  "required": [
    "task_id"
  ],
  "title": "TaskIdResponse"
}

Get routing result

Path Parameters

Name, Type	Description
task_id Required string	The ID of the routing task. This ID is returned by the '/routing/routing' POST endpoint.

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

GET

/routing/routing/{task_id}

curl -X GET \
  https://cloud-transpiler.quantum.ibm.com/routing/routing/{task_id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

import requests
 
response = requests.request(
    "GET",
    "https://cloud-transpiler.quantum.ibm.com/routing/routing/{task_id}",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
)
print(response.json())

Responses

Status code

{
  "state": "example",
  "result": null
}

Status code

{
  "properties": {
    "state": {
      "type": "string",
      "title": "State"
    },
    "result": {
      "anyOf": [
        {
          "properties": {
            "qasm": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Qasm"
            },
            "success": {
              "type": "boolean",
              "title": "Success"
            },
            "layout": {
              "anyOf": [
                {
                  "properties": {
                    "initial": {
                      "items": {
                        "type": "integer"
                      },
                      "type": "array",
                      "title": "Initial"
                    },
                    "final": {
                      "items": {
                        "type": "integer"
                      },
                      "type": "array",
                      "title": "Final"
                    }
                  },
                  "type": "object",
                  "required": [
                    "initial",
                    "final"
                  ],
                  "title": "LayoutResult",
                  "description": "Enum for layout result"
                },
                {
                  "type": "null"
                }
              ]
            },
            "error": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Error"
            }
          },
          "type": "object",
          "required": [
            "success"
          ],
          "title": "RlResult",
          "description": "Enum for Rl Result information"
        },
        {
          "items": {
            "properties": {
              "qasm": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Qasm"
              },
              "success": {
                "type": "boolean",
                "title": "Success"
              },
              "layout": {
                "anyOf": [
                  {
                    "properties": {
                      "initial": {
                        "items": {
                          "type": "integer"
                        },
                        "type": "array",
                        "title": "Initial"
                      },
                      "final": {
                        "items": {
                          "type": "integer"
                        },
                        "type": "array",
                        "title": "Final"
                      }
                    },
                    "type": "object",
                    "required": [
                      "initial",
                      "final"
                    ],
                    "title": "LayoutResult",
                    "description": "Enum for layout result"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "error": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Error"
              }
            },
            "type": "object",
            "required": [
              "success"
            ],
            "title": "RlResult",
            "description": "Enum for Rl Result information"
          },
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Result"
    }
  },
  "type": "object",
  "required": [
    "state"
  ],
  "title": "TaskResultResponse"
}