Use IBM Cloud Resource Controller API for instance management

You can use the IBM Cloud® Resource Controller REST API to programmatically get, create, and update instances.

All Resource Controller endpoints require that you authenticate by passing a header called Authorization with the bearer token. Refer to the REST API setup guide.

Get an instance

Use the GET /v2/resource_instances/{crn} endpoint to get information about a particular instance. The CRN must be URL-encoded in the path.

In addition to the standard Resource Controller fields, the response includes quantum-specific fields in both parameters and extensions. extensions stores the instance's normalized metadata, whereas parameters only stores the most recent request to modify the instance. Therefore, you should read from extensions rather than parameters.

The extensions object includes these fields:

• instance_limit_seconds — Integer, or null. The usage time limit for the instance. See Set instance allocation limits.
• usage_allocation_seconds — Integer, or null. The time allocated to this instance, used by the fair-share scheduler to determine queue priority. See Set instance allocation limits.
• backends — Array of strings. The allowlist of backend names available to this instance. ["ANY"] means all backends on the plan are available (the default). [] means no backends are available.

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

import urllib.parse
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

resp = requests.get(
    url,
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Get a list of all instances

Use the GET /v2/resource_instances endpoint to get a list of all your instances. Set the resource_id query parameter to b6049020-80f4-11eb-a0f7-e35ec9b4054f to filter to IBM Quantum® instances.

If your account has multiple plans and you want to filter by plan, set the resource_plan_id query parameter to one of the following values:

Each result includes the same extensions field as described in Get an instance.

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

import requests

resp = requests.get(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f",
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Update an instance

Use the PATCH /v2/resource_instances/{crn} endpoint to update the limit, allocation, and permitted backends for an instance. The CRN must be URL-encoded in the path.

Pass a parameters JSON object in the request body with the fields you want to change, along with the header "Content-Type: application/json". Omitted fields are left unchanged.

• instance_limit_seconds — Integer, or null. The usage time limit for the instance. See Set instance allocation limits.
• usage_allocation_seconds — Integer, or null. The time allocated to this instance, used by the fair-share scheduler to determine queue priority. See Set instance allocation limits. Not applicable to Pay-As-You-Go instances.
• backends — Array of strings. The allowlist of backend names available to this instance. ["ANY"] means all backends on the plan are available. [] means no backends are available.

The endpoint's response is similar to getting an instance, including how it handles the extensions object.

curl \
--request PATCH \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data "{
    \"parameters\": {
        \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",
        \"usage_allocation_seconds\": 220
    }
}"

import urllib.parse
import datetime
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
body = {
    "parameters": {
        "timestamp": timestamp,
        "usage_allocation_seconds": 220,
    }
}

resp = requests.patch(
    url,
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Create a new instance

Use the POST /v2/resource_instances endpoint to create (provision) a new instance. Pass a JSON body with the header "Content-Type: application/json".

Required fields:

• name — A human-readable name for the instance.
• target — The region, such as us-east or eu-de.
• resource_plan_id — The plan for this instance. See the plan ID table.
• resource_group — The resource group to use.

You can also include a parameters object to set quantum-specific values:

• instance_limit_seconds — Integer, or null. The usage time limit for the instance. See Set instance allocation limits.
• usage_allocation_seconds — Integer, or null. The time allocated to this instance, used by the fair-share scheduler to determine queue priority. See Set instance allocation limits. Not applicable to Pay-As-You-Go instances.
• backends — Array of strings. The allowlist of backend names available to this instance. ["ANY"] means all backends on the plan are available. [] means no backends are available.

curl \
  --request POST \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "name": "my-new-instance",
      "target": "us-east",
      "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
      "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
      "parameters": {
          "instance_limit_seconds": 300,
          "usage_allocation_seconds": 220
      }
  }'

import requests

body = {
    "name": "my-new-instance",
    "target": "us-east",
    "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
    "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
    "parameters": {
        "instance_limit_seconds": 300,
        "usage_allocation_seconds": 220,
    },
}

resp = requests.post(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())