Transpiler methods

Qiskit & AI transpiler methods

Transpile circuits

Transpile abstract circuits into a circuit that obeys the backend's instruction set architecture (ISA), either using Qiskit SDK or AI-powered transpilation. Returns a task ID; use the '/transpile/{taskId}' endpoint to get the result.

Query Parameters

Name, Type	Description
backend string	The name of the backend to transpile the circuit for. Refer to https://docs.quantum.ibm.com/run/get-backend-information. If not specified, you must specify `backend_coupling_map` in the request body. Example: `"ibm_kyoto"`
optimization_level integer	How much to optimize the circuit. Refer to https://docs.quantum.ibm.com/transpile/set-optimization Default value: `3`
use_ai boolean	Deprecated: Use the `ai` parameter instead.
ai string	Whether to use the Qiskit SDK transpile function, the AI-powered features, or let the service to select the best method. Possible values: `truefalseauto` Default value: `auto`
ai_layout_mode string	Specifies how to handle the layout selection Possible values: `keepoptimizeimprove` Default value: `optimize`
use_fractional_gates boolean	Wether to use fractional gates or not in the transpilation process Default value: `false`

Body Parameters (application/json)

Name, Type	Description
qasm_circuits string[] \| string \| null	One or more OpenQASM circuits to transpile. 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];","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];"]`
qpy_circuits string \| null	One or more QPY circuits to transpile. QPY circuits must be encoded in Base64. Example: "UUlTS0lUDAECAgAAAAAAAAACZXEAC2YACAAAAAMAAAAAAAAAAAAAAAIAAAABAAAAAAAAAAMAAAAAY2lyY3VpdC0xNzcAAAAAAAAAAHt9cQEAAAADAAEBcQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAgAAAAAAAAAAAAcAAAAAAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAIAAAADQ0NYR2F0ZXEAAAAAcQAAAAJxAAAAAQAJAAAAAAAAAAMAAAAAAAAAAAAAAAAAAAAAAAABAAAAAUNTd2FwR2F0ZXEAAAAAcQAAAAFxAAAAAgAIAAAAAAAAAAMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFJDQ1hHYXRlcQAAAAFxAAAAAHEAAAACAAAA////////////////AAAAAAAAAAAAC2YACAAAAAMAAAAAAAAAAAAAAAIAAAABAAAAAAAAAAMAAAAAY2lyY3VpdC0xNzcAAAAAAAAAAHt9cQEAAAADAAEBcQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAgAAAAAAAAAAAAcAAAAAAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAIAAAADQ0NYR2F0ZXEAAAAAcQAAAAJxAAAAAQAJAAAAAAAAAAMAAAAAAAAAAAAAAAAAAAAAAAABAAAAAUNTd2FwR2F0ZXEAAAAAcQAAAAFxAAAAAgAIAAAAAAAAAAMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFJDQ1hHYXRlcQAAAAFxAAAAAHEAAAACAAAA////////////////AAAAAAAAAAA="
qiskit_transpile_options object \| null	Dictionary with inputs to configure the transpile endpoint. Accepts the same inputs as the Qiskit transpile() method https://docs.quantum.ibm.com/api/qiskit/compiler#transpile, except for `circuits` and `backend`. Example: `{"basis_gates":["u1","u2","u3","cx"],"seed_transpiler":0}`
backend_coupling_map integer[][] \| null	A list of pairs that represents physical links between qubits. Must be specified if the query parameter `backend` is not set. Example: `[[1,2],[2,1]]`
optimization_preferences string \| string[] \| null	Describe your preferences with a value or a list of values when prioritizing optimization. Allowed options: noise, n_cnots, n_gates, cnot_layers, layers. Example: `["noise","n_gates"]` Example: `"n_cnots"`

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

POST

/transpile

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

import requests
 
response = requests.request(
    "POST",
    "https://cloud-transpiler.quantum.ibm.com/transpile",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
)
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 transpilation result

Gets a task transpilation result. The Task ID needed for this endpoint is returned by /transpile

Path Parameters

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

HTTP Response Status Codes

Status code	Description
200	Successful Response
422	Validation Error

Code samples

GET

/transpile/{task_id}

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

import requests
 
response = requests.request(
    "GET",
    "https://cloud-transpiler.quantum.ibm.com/transpile/{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"
            },
            "qpy": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Qpy"
            },
            "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": "UnCompressedRlResult"
        },
        {
          "items": {
            "properties": {
              "qasm": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Qasm"
              },
              "qpy": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "title": "Qpy"
              },
              "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": "UnCompressedRlResult"
          },
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Result"
    }
  },
  "type": "object",
  "required": [
    "state"
  ],
  "title": "TaskResultResponse"
}