ibm-quantum Sessions API

openapi: 3.2.0
info:
  title: Qiskit Runtime Sessions API
  description: The Qiskit Runtime API description
  version: 0.56.3
  contact: {}
  x-ibm-changelog: '- `GET /api/v1/jobs/:id/metrics` and `GET /api/v1/jobs` return usage data using a different response format. The APIs no longer return the response properties `usage.circuits_execution_time_ns`. Now `GET /api/v1/jobs/:id/metrics` will return `circuits_execution_time_ns` at response root level.'
servers:
- url: /api
tags:
- name: Sessions
paths:
  /v1/sessions:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    post:
      tags:
      - Sessions
      summary: Create a session
      operationId: create_session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSession'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContainer'
        '401':
          description: Unauthorized
          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.session.create
      x-ibm-permissions:
        actions:
        - name: quantum-computing.session.create
  /v1/sessions/{id}:
    parameters:
    - schema:
        type: string
      name: id
      description: Job Session ID
      in: path
      required: true
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      tags:
      - Sessions
      summary: Get a session
      operationId: get_session
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSession'
        '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.session.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.session.read
    patch:
      tags:
      - Sessions
      summary: Update a session
      operationId: update_session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionRequest'
      responses:
        '204':
          description: Successfully updated session
        '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.session.update
      x-ibm-permissions:
        actions:
        - name: quantum-computing.session.update
  /v1/sessions/{id}/close:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    delete:
      tags:
      - Sessions
      summary: Close job session
      operationId: delete_session_close
      parameters:
      - schema:
          type: string
          pattern: ^.*$
          minLength: 1
          maxLength: 500
        name: id
        description: Session Id
        in: path
        required: true
      responses:
        '204':
          description: Successfully closed runtime session
      description: 'Closes the runtime session. The session stops accepting new jobs and queued jobs will not run.

        Existing running jobs will run to completion. This is analogous to the `cancel()` function in Qiskit.'
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.session.update
      x-ibm-permissions:
        actions:
        - name: quantum-computing.session.update
components:
  schemas:
    SessionTimestamp:
      type: object
      description: Contains information about the time a specific status transition happened
      properties:
        status:
          $ref: '#/components/schemas/SessionState'
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the session transitioned into the given status
      required:
      - status
      - timestamp
    SessionState:
      type: string
      enum:
      - open
      - active
      - inactive
      - closed
      description: 'The state of the session.

        - open: The session is waiting to run jobs.

        - active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.

        - inactive: The session does not have priority and is not running any jobs.

        - closed: The session is not running any jobs and will not accept/run new jobs.

        '
    CreateSessionRequestCloud:
      allOf:
      - $ref: '#/components/schemas/BaseCreateSessionRequest'
      - description: Request to create a session. Only for use with IBM Cloud Channel.
      example:
        mode: dedicated
        max_ttl: 28800
        backend: ibm_backend
    UsageDetailMetric:
      title: UsageDetailMetric
      description: Identifies the metric definition from which a usage detail was calculated.
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The identifier of the metric definition from which this usage was calculated.
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          minLength: 36
          maxLength: 36
        value:
          type: number
          description: The amount of usage for this metric, in seconds.
          minimum: 0
      required:
      - id
      - value
    ExecutionMode:
      type: string
      description: Execution mode to run the session in
      enum:
      - batch
      - dedicated
    CreateSessionRequestChannelPartner:
      allOf:
      - $ref: '#/components/schemas/BaseCreateSessionRequest'
      type: object
      description: Request to create a session. Only for use by channel partner.
      properties:
        interactive_ttl:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          description: The maximum time (in seconds) between jobs to keep the session active. Must be less than or equal to `active_ttl`.
        active_ttl:
          type: integer
          format: int32
          minimum: 1
          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`. Defaults to `max_ttl`.
      required:
      - interactive_ttl
      example:
        interactive_ttl: 1
        max_ttl: 28800
        active_ttl: 28800
        mode: batch
        backend: ibm_backend
    SessionUsage:
      title: Usage
      description: The usage for the session split into billable metrics if there are multiple.
      type: object
      properties:
        value:
          type: number
          format: float
          description: The amount of usage for this metric, in resource units.
          minimum: 0
        unit:
          type: string
          description: The unit of the value field.
          enum:
          - resource_units
        details:
          type: array
          description: A breakdown of the usage by metric.
          minItems: 1
          items:
            $ref: '#/components/schemas/UsageDetail'
      required:
      - value
      - unit
      - details
    SessionStateReason:
      type: string
      description: The reason for the state change.
    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
    JobSession:
      type: object
      description: Job session
      properties:
        id:
          type: string
          description: Job ID
        backend_name:
          type:
          - string
          - 'null'
          description: Backend name. May not be set when in the "open" state.
        started_at:
          type: string
          format: date-time
          description: Timestamp of when the session was started
        activated_at:
          type: string
          format: date-time
          description: Timestamp of when the session state was changed to active
        closed_at:
          type: string
          format: date-time
          description: Timestamp of when the session was closed
        last_job_started:
          type: string
          format: date-time
          description: Timestamp of when the last job in the session started
        last_job_completed:
          type: string
          format: date-time
          description: Timestamp of when the last job in the session completed
        interactive_ttl:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          description: The maximum time (in seconds) between jobs to keep the session active
        max_ttl:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          description: The maximum time (in seconds) for session to run, subject to plan limits
        active_ttl:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          description: The remaining time (in seconds) for the session to be in the active state while jobs are running.
        state:
          $ref: '#/components/schemas/SessionState'
        state_reason:
          $ref: '#/components/schemas/SessionStateReason'
        accepting_jobs:
          $ref: '#/components/schemas/AcceptingJobs'
        mode:
          $ref: '#/components/schemas/ExecutionMode'
        timestamps:
          type: array
          items:
            $ref: '#/components/schemas/SessionTimestamp'
        user_id:
          type: string
          description: The id of the user who created the session.
        elapsed_time:
          type: number
          description: Usage in seconds. Can be null for ongoing sessions.
          example: 2
        usage:
          $ref: '#/components/schemas/SessionUsage'
      required:
      - id
      - backend_name
      - mode
    UsageDetail:
      title: UsageDetail
      description: A single billable metric contributing to a job's overall usage.
      type: object
      properties:
        value:
          type: number
          format: float
          description: The amount of usage for this metric, in resource units.
          minimum: 0
        unit:
          type: string
          description: The unit of the value field.
          enum:
          - resource_units
        metric:
          $ref: '#/components/schemas/UsageDetailMetric'
      required:
      - value
      - unit
      - metric
    CreateSessionRequest:
      oneOf:
      - $ref: '#/components/schemas/CreateSessionRequestCloud'
      - $ref: '#/components/schemas/CreateSessionRequestChannelPartner'
    UpdateSessionRequest:
      type: object
      properties:
        accepting_jobs:
          $ref: '#/components/schemas/AcceptingJobs'
      required:
      - accepting_jobs
    AcceptingJobs:
      type: boolean
      description: If true, the session is actively accepting new jobs to be queued. If false, jobs will be rejected on create and the session will be immediately closed when there are no more jobs to run in the session.
    BaseCreateSessionRequest:
      type: object
      description: Base request schema to create a session.
      properties:
        max_ttl:
          type: integer
          description: The maximum time (in seconds) for the session to run, subject to plan limits.
          format: int32
          minimum: 1
          maximum: 2147483647
          default: 28800
        mode:
          $ref: '#/components/schemas/ExecutionMode'
        backend:
          type: string
          description: Backend name
        backend_name:
          type: string
          description: Backend name (fallback)
      required:
      - mode
  parameters:
    IBM-API-Version:
      in: header
      name: IBM-API-Version
      required: true
      description: API version to use
      schema:
        type: string
        minLength: 10
        maxLength: 10
        pattern: ^\d{4}-\d{2}-\d{2}$
        default: '2024-01-01'
        example: '2026-04-15'
  securitySchemes:
    IBMCloudAPIKey:
      type: apiKey
      in: header
      name: Authorization
      description: IBM Cloud Identity and Access Management (IAM) API key. In the format 'apikey <IBM Cloud API Key>'.
    ServiceCRN:
      type: apiKey
      in: header
      name: Service-CRN
      description: The Cloud Resource Name (CRN) of your Qiskit Runtime service instance
    IBMCloudAuth:
      scheme: bearer
      bearerFormat: jwt
      type: http
      description: IBM Cloud Identity and Access Management (IAM) access token
x-provenance:
  method: harvested
  publisher: IBM Quantum
  source: https://quantum.cloud.ibm.com/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)