openapi: 3.0.0
info:
  title: Qiskit Runtime Instances API
  version: 0.45.3
  description: Inspect the current Qiskit Runtime instance, view instance configuration and limits, and read per-account configuration on IBM Quantum Platform.
  contact:
    name: IBM Quantum
    url: https://quantum.cloud.ibm.com
  license:
    name: IBM
    url: https://www.ibm.com/legal
servers:
- url: https://quantum.cloud.ibm.com/api
  description: Global region
- url: https://eu-de.quantum.cloud.ibm.com/api
  description: EU-DE region
tags:
- name: Instances
- name: Accounts
paths:
  /v1/instance:
    get:
      tags:
      - Instances
      summary: Get Current Instance Details
      description: Returns the details of the current logged in instance, using CRN from the request header.
      operationId: get_instance
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                backends:
                - ibm_backend
                instance_limit: 60.7
                instance_limit_seconds: '61'
                plan_id: flex-plan-id-1
                usage_allocation_seconds: '200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.instance.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.instance.read
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
  /v1/instances/configuration:
    get:
      tags:
      - Instances
      summary: Get Instance Configuration
      description: Returns the configuration for the specified instance e.g. instance limit in seconds, using CRN from the request header.
      operationId: get_instance_configuration
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceConfiguration'
              examples:
                sampleInstanceConfigurationResponse:
                  $ref: '#/components/examples/sampleInstanceConfigurationResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.instance.configuration.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.instance.configuration.read
    put:
      x-codegen-request-body-name: instance_update
      tags:
      - Instances
      summary: Update Instance Configuration
      operationId: replace_instance_configuration
      description: Update the configuration for the specified instance e.g. instance limit in seconds, using CRN from context params of the request.
      responses:
        '204':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '409':
          description: Usage exceeds instance limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceConfigurationUpdate'
        description: Request body for updating a specified instance configuration.
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.instance.configuration.update
      x-ibm-permissions:
        actions:
        - name: quantum-computing.instance.configuration.update
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
  /v1/accounts/{id}:
    get:
      operationId: get_account
      summary: Get Account Configuration
      description: Get the current account information. If no account information is found, returns the default configuration.
      parameters:
      - schema:
          type: string
          pattern: ^.+$
          minLength: 1
          maxLength: 64
        name: plan_id
        in: query
        required: false
        description: Obtain the account configuration only for the specified plan
      tags:
      - Accounts
      responses:
        '200':
          description: Account configuration successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpandedAccountConfiguration'
              examples:
                accountConfigurationExample:
                  $ref: '#/components/examples/expandedAccountConfigurationExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.account-configuration.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.account-configuration.read
    parameters:
    - schema:
        type: string
        minLength: 1
        maxLength: 64
        pattern: ^[a-zA-Z0-9-_]+$
      name: id
      in: path
      required: true
      description: Account id (without `a/` prefix)
    - $ref: '#/components/parameters/IBM-API-Version'
  /v1/instances/usage:
    get:
      description: Get instance usage
      operationId: get_usage
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: Get Instance Usage
      tags:
      - Instances
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.instance-usage.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.instance-usage.read
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
components:
  schemas:
    ErrorContainer:
      description: Error response
      type: object
      properties:
        trace:
          type: string
          description: A request identifier
        errors:
          type: array
          description: A list of errors
          items:
            type: object
            properties:
              code:
                type: string
                description: Error type identifier
              message:
                description: Explanation of the problem
                type: string
              more_info:
                description: URL where information about the error can be read in a web browser
                type: string
    ExpandedAccountConfiguration:
      type: object
      description: Configuration for an account managed by the IBM Qiskit Runtime service.
      properties:
        plans:
          description: The list of configurations for the account per plan
          type: array
          items:
            $ref: '#/components/schemas/ExpandedPlanConfiguration'
          minItems: 0
          maxItems: 20
      required:
      - plans
    ExpandedPlanConfiguration:
      allOf:
      - $ref: '#/components/schemas/PlanConfiguration'
      - type: object
        properties:
          unallocated_usage_seconds:
            type: integer
            format: int32
            minimum: 0
            maximum: 2147483647
            description: The remaining usage allocation that can still be allocated to instances.
    FunctionConfig:
      type: object
      description: A function available to an account plan.
      properties:
        provider:
          type: string
          description: The function provider name.
          pattern: ^.+$
          minLength: 1
          maxLength: 256
          example: ibm
        name:
          type: string
          description: The function name, unique within a provider.
          pattern: ^.+$
          minLength: 1
          maxLength: 256
          example: circuit-function
        business_model:
          type: string
          description: The business model under which the function is offered.
          enum:
          - trial
          - subsidized
          - consumption
        permissions:
          type: array
          description: IAM-style actions granted for this function.
          items:
            type: string
            pattern: ^.+$
            minLength: 1
            maxLength: 256
          minItems: 1
          maxItems: 2147483647
          example:
          - function.run
      required:
      - provider
      - name
      - business_model
      - permissions
    GenericError:
      type: object
      properties:
        code:
          type: number
          example: 1000
        message:
          type: string
          example: message
        solution:
          type: string
          example: This is a possible solution
        more_info:
          type: string
      required:
      - code
      - message
      - solution
      - more_info
    GenericErrorDto:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GenericError'
        trace:
          type: string
          description: Transaction ID for tracing the request
          example: fdda765f-fc57-4d3c-9a2f-5d8b8b9e6e8a
          pattern: ^.*$
          format: uuid
          minLength: 1
          maxLength: 100
      required:
      - errors
      - trace
    GetUsageResponse:
      type: object
      properties:
        instance_id:
          type: string
        plan_id:
          type: string
        usage_period:
          description: Start and end time of the usage period
          allOf:
          - $ref: '#/components/schemas/UsagePeriod'
        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
    Instance:
      type: object
      description: Instance
      properties:
        backends:
          type: array
          description: List of backend systems or clusters associated with the service instance
          items:
            type: string
            pattern: ^.*$
            minLength: 1
            maxLength: 128
            nullable: false
          minItems: 0
          maxItems: 100
        instance_limit:
          type: number
          format: double
          description: Represents the instance limits in seconds; will be replaced by instance_limit_seconds
          deprecated: true
        instance_limit_seconds:
          type: string
          description: Specifies the maximum number of resources time that can run on this instance
        plan_id:
          type: string
          description: Identifier for the service plan associated with the instance as defined in Global Catalog
          pattern: ^.*$
          minLength: 1
          maxLength: 128
        usage_allocation_seconds:
          type: string
          description: The maximum sum of allowable usage allocation on the instance.
    InstanceConfiguration:
      type: object
      description: Instance configuration
      properties:
        instance_limit:
          type: number
          format: double
          description: Instance usage limit in seconds
    InstanceConfigurationUpdate:
      type: object
      description: instance configuration update
      properties:
        instance_limit:
          type: integer
          format: int32
          description: This field can be null or an integer. Use null to reset/remove the instance limit.
          minimum: 1
          maximum: 2147483647
    PlanConfiguration:
      type: object
      properties:
        plan_id:
          type: string
          description: The plan id as defined in Global Catalog
          pattern: ^.+$
          minLength: 1
          maxLength: 128
        subscription_id:
          type: string
          description: The id of subscription to identify each plan contract in one account
          pattern: ^.+$
          minLength: 1
          maxLength: 36
        subscription_name:
          type: string
          description: The user-readable name of the subscription
          pattern: ^.+$
          minLength: 1
          maxLength: 128
        usage_allocation_seconds:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: The maximum sum of allowable usage allocation across all instances in the account. Mandatory when plan_id is about flex plan.
        usage_limit_seconds:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: The maximum amount of time workloads can run accross all instances in the account for the specified plan. Mandatory when plan_id is about flex plan.
        backends:
          type: array
          description: List of backends to allow the account to assign for instances.
          items:
            type: string
            pattern: ^.+$
            minLength: 1
            maxLength: 128
          minItems: 0
          maxItems: 100
        max_ttl:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: The maximum time (in seconds) for session to run, subject to plan limits.
        active_ttl:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: The remaining time (in seconds) for the session to be in the active state while jobs are running. Must be less than or equal to max ttl.
        interactive_ttl:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: The maximum time (in seconds) between jobs to keep the session active. Must be less than or equal to active ttl.
        start_time:
          type: string
          format: date-time
          description: Start time for contract-based plans. Mandatory when plan_id is about flex plan.
        end_time:
          type: string
          format: date-time
          description: End time for contract-based plans. Mandatory when plan_id is about flex plan.
        functions:
          type: array
          description: "Functions available to this account plan. Each entry specifies a function id, billing model, and the set of permitted actions. Unlike instance-level configuration, `[\"ANY\"]` is not a valid value \u2014 functions must be listed explicitly.\n"
          items:
            $ref: '#/components/schemas/FunctionConfig'
          minItems: 0
          maxItems: 2147483647
      required:
      - backends
      - plan_id
      - subscription_id
      - subscription_name
    UsagePeriod:
      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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: IBM Cloud IAM bearer token
    ServiceCRN:
      type: apiKey
      in: header
      name: Service-CRN
      description: IBM Cloud Service CRN identifying the Qiskit Runtime instance
    ApiVersion:
      type: apiKey
      in: header
      name: IBM-API-Version
      description: API version, e.g. 2026-03-15
security:
- BearerAuth: []
  ServiceCRN: []
  ApiVersion: []