openapi: 3.0.0
info:
  title: Qiskit Runtime Accounts Analytics API
  version: 0.45.3
  description: Read usage analytics and active workloads for a Qiskit Runtime instance, including by-time-window aggregations used to track Open / Pay-as-you-go / Flex / Premium minute consumption.
  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
security:
- BearerAuth: []
  ServiceCRN: []
  ApiVersion: []
tags:
- name: Analytics
paths:
  /v1/analytics/usage:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      description: Get usage analytics
      operationId: analytics_usage
      parameters:
      - name: instance
        required: false
        in: query
        schema:
          example: 'crn:v1:staging:public:quantum-computing:region:a/account:instance::'
          type: array
          items:
            type: string
      - name: interval_start
        required: false
        in: query
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: interval_end
        required: false
        in: query
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: backend
        required: false
        in: query
        schema:
          example: ibm_tenerife
          type: array
          items:
            type: string
      - name: user_id
        required: false
        in: query
        schema:
          example: '123'
          type: array
          items:
            type: string
      - name: simulators
        required: false
        in: query
        description: Include simulators
        schema:
          default: true
          example: false
          type: boolean
      - name: plan
        required: false
        in: query
        schema:
          example: premium
          type: array
          items:
            type: string
      - name: subscription_id
        required: false
        in: query
        description: The subscription ID whose analytics are being requested. Could be a single ID or an array of IDs.
        schema:
          minItems: 1
          maxItems: 200
          example:
          - 91b2c828-2952-4f05-aed8-bedf92c6c480
          type: array
          items:
            type: string
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
            minLength: 36
            maxLength: 36
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnalyticsUsageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: Get Usage Analytics
      tags:
      - Analytics
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.account-analytics-usage.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.account-analytics-usage.read
  /v1/analytics/usage_grouped:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      description: Get usage analytics grouped
      operationId: get_usage_analytics_grouped
      parameters:
      - name: group_by
        required: true
        in: query
        description: key to group usage by
        schema:
          minLength: 4
          maxLength: 15
          pattern: ^[a-z_]+$
          example: instance
          type: string
          enum:
          - instance
          - backend
          - user_id
          - plan
          - subscription_id
      - name: instance
        required: false
        in: query
        schema:
          example: 'crn:v1:staging:public:quantum-computing:region:a/account:instance::'
          type: array
          items:
            type: string
      - name: interval_start
        required: false
        in: query
        description: start date
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: interval_end
        required: false
        in: query
        description: end date
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: backend
        required: false
        in: query
        description: backend to filter by
        schema:
          example: ibm_tenerife
          type: array
          items:
            type: string
      - name: user_id
        required: false
        in: query
        schema:
          example: '123'
          type: array
          items:
            type: string
      - name: simulators
        required: false
        in: query
        description: Include simulators
        schema:
          default: true
          example: false
          type: boolean
      - name: plan
        required: false
        in: query
        schema:
          example: premium
          type: array
          items:
            type: string
      - name: subscription_id
        required: false
        in: query
        description: The subscription ID whose analytics are being requested. Could be a single ID or an array of IDs.
        schema:
          minItems: 1
          maxItems: 200
          example:
          - 91b2c828-2952-4f05-aed8-bedf92c6c480
          type: array
          items:
            type: string
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
            minLength: 36
            maxLength: 36
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnalyticsUsageGroupedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: Get Usage Analytics Grouped
      tags:
      - Analytics
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.account-analytics-usage.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.account-analytics-usage.read
  /v1/analytics/usage_grouped_by_date:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      description: Get usage analytics grouped by date
      operationId: get_usage_analytics_grouped_by_date
      parameters:
      - name: group_by
        required: true
        in: query
        description: key to group usage by
        schema:
          minLength: 8
          maxLength: 8
          pattern: ^[a-z_]+$
          example: instance
          type: string
          enum:
          - instance
      - name: instance
        required: false
        in: query
        schema:
          example: 'crn:v1:staging:public:quantum-computing:region:a/account:instance::'
          type: array
          items:
            type: string
      - name: interval_start
        required: false
        in: query
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: interval_end
        required: false
        in: query
        schema:
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          type: string
      - name: backend
        required: false
        in: query
        schema:
          example: ibm_tenerife
          type: array
          items:
            type: string
      - name: user_id
        required: false
        in: query
        schema:
          example: '123'
          type: array
          items:
            type: string
      - name: simulators
        required: false
        in: query
        description: Include simulators
        schema:
          default: true
          example: false
          type: boolean
      - name: plan
        required: false
        in: query
        schema:
          example: premium
          type: array
          items:
            type: string
      - name: subscription_id
        required: false
        in: query
        description: The subscription ID whose analytics are being requested. Could be a single ID or an array of IDs.
        schema:
          minItems: 1
          maxItems: 200
          example:
          - 91b2c828-2952-4f05-aed8-bedf92c6c480
          type: array
          items:
            type: string
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
            minLength: 36
            maxLength: 36
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnalyticsUsageGroupedByDateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: Get Usage Analytics Grouped by Date
      tags:
      - Analytics
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.account-analytics-usage.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.account-analytics-usage.read
  /v1/analytics/filters:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      description: Get analytics filters
      operationId: analytics_filters
      parameters:
      - name: instance
        required: false
        in: query
        schema:
          example: 'crn:v1:staging:public:quantum-computing:region:a/account:instance::'
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnalyticsFiltersResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: Get Analytics Filters
      tags:
      - Analytics
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.account-analytics-filters.read
      x-ibm-permissions:
        actions:
        - name: quantum-computing.account-analytics-filters.read
components:
  schemas:
    SubscriptionFilter:
      type: object
      properties:
        id:
          type: string
          example: 7f666d17-7893-47d8-bf9d-2b2389fc4dfc
        name:
          type: string
          example: premium
      required:
      - id
      - name
    InstanceFilter:
      type: object
      properties:
        id:
          type: string
          example: 'crn:v1:staging:public:quantum-computing:region:a/account:'
        deleted:
          type: boolean
      required:
      - id
      - deleted
    GetAnalyticsUsageGroupedResponse:
      type: object
      properties:
        data:
          description: Data
          type: array
          items:
            $ref: '#/components/schemas/GetAnalyticsUsageGroupedResponseData'
      required:
      - data
    UserFilter:
      type: object
      properties:
        id:
          type: string
          example: '123'
      required:
      - id
    PlanFilter:
      type: object
      properties:
        name:
          type: string
          example: premium
      required:
      - name
    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
    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
    GetAnalyticsFiltersResponse:
      type: object
      properties:
        backends:
          type: array
          items:
            $ref: '#/components/schemas/BackendFilter'
        instances:
          type: array
          items:
            $ref: '#/components/schemas/InstanceFilter'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserFilter'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/PlanFilter'
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionFilter'
      required:
      - backends
      - instances
      - users
      - plans
      - subscriptions
    BackendFilter:
      type: object
      properties:
        name:
          type: string
          example: simulator
      required:
      - name
    GetAnalyticsUsageResponse:
      type: object
      properties:
        usage:
          type: number
          example: 10
          description: Total usage (in milliseconds)
        jobs:
          type: number
          example: 10
          description: Total number of jobs
        sessions:
          type: number
          example: 10
          description: Total number of sessions
        sessions_usage:
          type: number
          example: 10
          description: Total sessions usage (in milliseconds)
        avg_sessions_usage:
          type: number
          example: 10
          description: Average sessions usage (in milliseconds)
        max_sessions_usage:
          type: number
          example: 10
          description: Max sessions usage (in milliseconds)
        batch_sessions:
          type: number
          example: 10
          description: Total number of batch sessions
        batch_sessions_usage:
          type: number
          example: 10
          description: Total batch sessions usage (in milliseconds)
        avg_batch_sessions_usage:
          type: number
          example: 10
          description: Average batch sessions usage (in milliseconds)
        max_batch_sessions_usage:
          type: number
          example: 10
          description: Max batch sessions usage (in milliseconds)
        dedicated_sessions:
          type: number
          example: 10
          description: Total number of dedicated sessions
        dedicated_sessions_usage:
          type: number
          example: 10
          description: Total dedicated sessions usage (in milliseconds)
        avg_dedicated_sessions_usage:
          type: number
          example: 10
          description: Average dedicated sessions usage (in milliseconds)
        max_dedicated_sessions_usage:
          type: number
          example: 10
          description: Max dedicated sessions usage (in milliseconds)
        individual_jobs:
          type: number
          example: 10
          description: Total number of individual jobs
        individual_jobs_usage:
          type: number
          example: 10
          description: Total individual jobs usage  (in milliseconds)
        avg_individual_jobs_usage:
          type: number
          example: 10
          description: Average individual jobs usage  (in milliseconds)
        max_individual_jobs_usage:
          type: number
          example: 10
          description: Max individual jobs usage (in milliseconds)
        queue_time:
          type: number
          example: 10
          description: Total queue time (in milliseconds)
        avg_queue_time:
          type: number
          example: 10
          description: Average queue time (in milliseconds)
        max_queue_time:
          type: number
          example: 10
          description: Max queue time  (in milliseconds)
      required:
      - usage
      - jobs
      - sessions
      - sessions_usage
      - avg_sessions_usage
      - max_sessions_usage
      - batch_sessions
      - batch_sessions_usage
      - avg_batch_sessions_usage
      - max_batch_sessions_usage
      - dedicated_sessions
      - dedicated_sessions_usage
      - avg_dedicated_sessions_usage
      - max_dedicated_sessions_usage
      - individual_jobs
      - individual_jobs_usage
      - avg_individual_jobs_usage
      - max_individual_jobs_usage
      - queue_time
      - avg_queue_time
      - max_queue_time
    GetAnalyticsUsageGroupedResponseData:
      type: object
      properties:
        key:
          type: string
          example: ibm-q/main/open
          description: Grouping key
          nullable: true
        usage:
          type: number
          example: 10
          description: Total usage (in milliseconds)
        jobs:
          type: number
          example: 10
          description: Total number of jobs
        sessions:
          type: number
          example: 10
          description: Total number of sessions
        sessions_usage:
          type: number
          example: 10
          description: Total sessions usage (in milliseconds)
        avg_sessions_usage:
          type: number
          example: 10
          description: Average sessions usage (in milliseconds)
        max_sessions_usage:
          type: number
          example: 10
          description: Max sessions usage (in milliseconds)
        batch_sessions:
          type: number
          example: 10
          description: Total number of batch sessions
        batch_sessions_usage:
          type: number
          example: 10
          description: Total batch sessions usage (in milliseconds)
        avg_batch_sessions_usage:
          type: number
          example: 10
          description: Average batch sessions usage (in milliseconds)
        max_batch_sessions_usage:
          type: number
          example: 10
          description: Max batch sessions usage (in milliseconds)
        dedicated_sessions:
          type: number
          example: 10
          description: Total number of dedicated sessions
        dedicated_sessions_usage:
          type: number
          example: 10
          description: Total dedicated sessions usage (in milliseconds)
        avg_dedicated_sessions_usage:
          type: number
          example: 10
          description: Average dedicated sessions usage (in milliseconds)
        max_dedicated_sessions_usage:
          type: number
          example: 10
          description: Max dedicated sessions usage (in milliseconds)
        individual_jobs:
          type: number
          example: 10
          description: Total number of individual jobs
        individual_jobs_usage:
          type: number
          example: 10
          description: Total individual jobs usage  (in milliseconds)
        avg_individual_jobs_usage:
          type: number
          example: 10
          description: Average individual jobs usage  (in milliseconds)
        max_individual_jobs_usage:
          type: number
          example: 10
          description: Max individual jobs usage (in milliseconds)
        queue_time:
          type: number
          example: 10
          description: Total queue time (in milliseconds)
        avg_queue_time:
          type: number
          example: 10
          description: Average queue time (in milliseconds)
        max_queue_time:
          type: number
          example: 10
          description: Max queue time  (in milliseconds)
      required:
      - key
      - usage
      - jobs
      - sessions
      - sessions_usage
      - avg_sessions_usage
      - max_sessions_usage
      - batch_sessions
      - batch_sessions_usage
      - avg_batch_sessions_usage
      - max_batch_sessions_usage
      - dedicated_sessions
      - dedicated_sessions_usage
      - avg_dedicated_sessions_usage
      - max_dedicated_sessions_usage
      - individual_jobs
      - individual_jobs_usage
      - avg_individual_jobs_usage
      - max_individual_jobs_usage
      - queue_time
      - avg_queue_time
      - max_queue_time
    GetAnalyticsUsageGroupedByDateResponse:
      type: object
      properties:
        interval_start:
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: Interval start
        interval_end:
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: Interval end
        data:
          description: Results
          type: array
          items:
            $ref: '#/components/schemas/GetAnalyticsUsageGroupedByDateResponseData'
      required:
      - interval_start
      - interval_end
      - data
    GetAnalyticsUsageGroupedByDateResponseData:
      type: object
      properties:
        key:
          type: string
          example: ibm-q/open/main
          description: Group key. Depends on the groupBy query params.
        interval_start:
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: Interval start
        interval_end:
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: Interval end
        usage:
          type: number
          example: 10
          description: Total usage (in milliseconds)
        jobs:
          type: number
          example: 10
          description: Total number of jobs
        sessions:
          type: number
          example: 10
          description: Total number of sessions
        sessions_usage:
          type: number
          example: 10
          description: Total sessions usage (in milliseconds)
        avg_sessions_usage:
          type: number
          example: 10
          description: Average sessions usage (in milliseconds)
        max_sessions_usage:
          type: number
          example: 10
          description: Max sessions usage (in milliseconds)
        batch_sessions:
          type: number
          example: 10
          description: Total number of batch sessions
        batch_sessions_usage:
          type: number
          example: 10
          description: Total batch sessions usage (in milliseconds)
        avg_batch_sessions_usage:
          type: number
          example: 10
          description: Average batch sessions usage (in milliseconds)
        max_batch_sessions_usage:
          type: number
          example: 10
          description: Max batch sessions usage (in milliseconds)
        dedicated_sessions:
          type: number
          example: 10
          description: Total number of dedicated sessions
        dedicated_sessions_usage:
          type: number
          example: 10
          description: Total dedicated sessions usage (in milliseconds)
        avg_dedicated_sessions_usage:
          type: number
          example: 10
          description: Average dedicated sessions usage (in milliseconds)
        max_dedicated_sessions_usage:
          type: number
          example: 10
          description: Max dedicated sessions usage (in milliseconds)
        individual_jobs:
          type: number
          example: 10
          description: Total number of individual jobs
        individual_jobs_usage:
          type: number
          example: 10
          description: Total individual jobs usage  (in milliseconds)
        avg_individual_jobs_usage:
          type: number
          example: 10
          description: Average individual jobs usage  (in milliseconds)
        max_individual_jobs_usage:
          type: number
          example: 10
          description: Max individual jobs usage (in milliseconds)
        queue_time:
          type: number
          example: 10
          description: Total queue time (in milliseconds)
        avg_queue_time:
          type: number
          example: 10
          description: Average queue time (in milliseconds)
        max_queue_time:
          type: number
          example: 10
          description: Max queue time  (in milliseconds)
      required:
      - key
      - interval_start
      - interval_end
      - usage
      - jobs
      - sessions
      - sessions_usage
      - avg_sessions_usage
      - max_sessions_usage
      - batch_sessions
      - batch_sessions_usage
      - avg_batch_sessions_usage
      - max_batch_sessions_usage
      - dedicated_sessions
      - dedicated_sessions_usage
      - avg_dedicated_sessions_usage
      - max_dedicated_sessions_usage
      - individual_jobs
      - individual_jobs_usage
      - avg_individual_jobs_usage
      - max_individual_jobs_usage
      - queue_time
      - avg_queue_time
      - max_queue_time
  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