Instances

Get current instance details

Returns the details of the current logged in instance, using CRN from the request header.

HTTP Response Status Codes

Status code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/v1/instance

curl -X GET \
  /api/v1/instance \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/instance",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

{
  "qctrl_enabled": true
}

Status code

{
  "type": "object",
  "description": "Instance",
  "properties": {
    "qctrl_enabled": {
      "type": "boolean",
      "description": "Says whether instance is configured to run jobs using Q-Ctrl channel strategy",
      "deprecated": true
    }
  }
}

Get instance configuration

Returns the configuration for the specified instance e.g. instance limit in seconds, using CRN from the request header.

HTTP Response Status Codes

Status code	Description
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

Code samples

GET

/v1/instances/configuration

curl -X GET \
  /api/v1/instances/configuration \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/instances/configuration",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

{
  "instance_limit": 123456
}

Status code

{
  "type": "object",
  "description": "Instance configuration",
  "properties": {
    "instance_limit": {
      "type": "number",
      "format": "double",
      "description": "Instance usage limit in seconds"
    }
  }
}

Update instance configuration

Update the configuration for the specified instance e.g. instance limit in seconds, using CRN from context params of the request.

Body Parameters (application/json)

Name, Type	Description
instance_limit integer	This field can be null or an integer. Use null to reset/remove the instance limit.

HTTP Response Status Codes

Status code	Description
204	OK
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Usage exceeds instance limit

Code samples

PUT

/v1/instances/configuration

curl -X PUT \
  /api/v1/instances/configuration \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "PUT",
    "/api/v1/instances/configuration",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

Get instance usage

HTTP Response Status Codes

Status code	Description
200
401	Unauthorized

Code samples

GET

/v1/instances/usage

curl -X GET \
  /api/v1/instances/usage \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/instances/usage",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
print(response.json())

Responses

Status code

{
  "instance_id": "example",
  "plan_id": "example",
  "usage_period": null,
  "usage_consumed_seconds": 12,
  "usage_limit_seconds": 60,
  "usage_allocation_seconds": 120,
  "usage_limit_reached": true
}

Status code

{
  "type": "object",
  "properties": {
    "instance_id": {
      "type": "string"
    },
    "plan_id": {
      "type": "string"
    },
    "usage_period": {
      "description": "Start and end time of the usage period",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "start_time": {
              "format": "date-time",
              "type": "string",
              "description": "The start time of the usage"
            },
            "end_time": {
              "format": "date-time",
              "type": "string",
              "description": "The end time of the usage"
            }
          }
        }
      ]
    },
    "usage_consumed_seconds": {
      "type": "number",
      "example": 12,
      "description": "Usage consumed in the current usage period"
    },
    "usage_limit_seconds": {
      "type": "number",
      "example": 60,
      "description": "The usage limit in seconds during the usage period"
    },
    "usage_allocation_seconds": {
      "type": "number",
      "example": 120,
      "description": "The seconds that are allocated for the instance during the usage period"
    },
    "usage_limit_reached": {
      "type": "boolean",
      "example": false,
      "description": "true if the usage limit is reached. false if not reached. undefined if usage limits do not apply to this instance."
    }
  },
  "required": [
    "instance_id",
    "plan_id",
    "usage_consumed_seconds"
  ]
}