openapi: 3.0.0
info:
  title: Qiskit Runtime Analytics Accounts Workloads 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: Workloads
paths:
  /v1/workloads:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      description: List user instance workloads
      operationId: find_instance_workloads
      parameters:
      - name: user
        required: false
        in: query
        description: User identifier. For now it can only be "me".
        schema:
          example: me
          type: string
          enum:
          - me
      - name: sort
        required: false
        in: query
        description: Field to sort the workloads by. A `-` prefix indicates descending sort order.
        schema:
          default: createdAt
          type: string
          enum:
          - createdAt
          - -createdAt
      - name: limit
        required: false
        in: query
        description: Number of workloads to return at a time
        schema:
          minimum: 1
          maximum: 50
          default: 10
          example: 5
          type: number
      - name: previous
        required: false
        in: query
        description: Cursor to previous workloads result page
        schema:
          type: string
      - name: next
        required: false
        in: query
        description: Cursor to next workloads result page
        schema:
          type: string
      - name: backend
        required: false
        in: query
        description: Backend name
        schema:
          example: ibm_seattle
          type: string
      - name: search
        required: false
        in: query
        description: Optional search string, used to filter workloads by id or tags
        schema:
          example: test
          type: string
      - name: status
        required: false
        in: query
        description: Status type to filter workloads by. It can be pending, in_progress, failed, completed or canceled.
        schema:
          example:
          - pending
          type: array
          items:
            type: string
            enum:
            - completed
            - canceled
            - failed
            - pending
            - in_progress
      - name: mode
        required: false
        in: query
        description: 'Workload mode: job, session or batch'
        schema:
          example: batch
          type: string
          enum:
          - job
          - session
          - batch
      - name: created_after
        required: false
        in: query
        description: Filter jobs and session created after this date
        schema:
          format: date-time
          example: '2021-01-01T00:00:00Z'
          type: string
      - name: created_before
        required: false
        in: query
        description: Filter jobs and session created before this date
        schema:
          format: date-time
          example: '2021-01-01T00:00:00Z'
          type: string
      - name: tags
        required: false
        in: query
        description: Optional array of tags for the workloads
        schema:
          example:
          - composer-info:composer:true
          - bar
          - foo
          type: array
          items:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationWorkloadsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericErrorDto'
      summary: List User Instance Workloads
      tags:
      - Workloads
      security:
      - IBMCloudAPIKey: []
      - ServiceCRN: []
      - IBMCloudAuth: []
      x-ibm-events:
        events:
        - name: quantum-computing.workload.list
      x-ibm-permissions:
        actions:
        - name: quantum-computing.workload.list
components:
  schemas:
    UsageResponse:
      type: object
      properties:
        qpu_charge_time_seconds:
          type: number
          description: The amount of resource usage in seconds. This value is used to calculate capacity consumption.
          example: 123
        status:
          type: string
          description: Status of billing data completeness. Only present for jobs. "pending" indicates billing data is still being processed. "complete" indicates billing data is final.
          example: complete
          enum:
          - pending
          - complete
      required:
      - qpu_charge_time_seconds
    WorkloadResponse:
      type: object
      properties:
        id:
          type: string
          description: Workload id (job and session id)
          example: ch8b1ok4k9li68vm059r
        created:
          type: string
          description: Creation date
          example: '2024-07-04T16:13:56.562Z'
        ended:
          type: string
          description: End date
          example: '2024-07-04T16:13:56.562Z'
        backend:
          type: string
          description: Backend name
          example: ibm_seattle
        instance:
          type: string
          description: Instance as hub/group/project
          example: ibmq/open/main
        user_id:
          type: string
          description: User id
          example: 65f0478ed32a1891af0a8d31
        accepting_jobs:
          type: boolean
          description: true if the session accepts jobs, false otherwise. Only for sessions, null for jobs
          example: true
          nullable: true
        mode:
          type: string
          description: 'Workload mode: job, session or batch'
          example: job
          enum:
          - job
          - session
          - batch
        status:
          type: string
          description: State for the workload.
          example: in_progress
          enum:
          - completed
          - canceled
          - failed
          - pending
          - in_progress
        status_reason:
          type: string
          description: Jobs only, status reason for the job
          example: Error occurred for job circuit-runner_ckodgbs1fc4b8ufrjsd0_d35e_2. Stale payload, retry maximum reached.
        tags:
          description: Tags for the jobs
          example:
          - test-job
          - foo
          - bar
          type: array
          items:
            type: string
        usage_seconds:
          type: number
          description: 'Usage in seconds. Can be null for ongoing workloads. DEPRECATED: Use `usage.qpu_charge_time_seconds` instead. This field will be removed in a future version.'
          example: 1
          deprecated: true
        usage:
          description: Usage information. Can be null for ongoing workloads.
          allOf:
          - $ref: '#/components/schemas/UsageResponse'
        estimated_running_time_seconds:
          type: number
          description: Estimated usage in seconds
          example: 1
      required:
      - id
      - created
      - backend
      - instance
      - user_id
      - mode
      - status
    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
    URLCursor:
      type: object
      properties:
        href:
          type: string
          example:
          - https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26
          - https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26
    PaginationWorkloadsResponse:
      type: object
      properties:
        workloads:
          type: array
          items:
            $ref: '#/components/schemas/WorkloadResponse'
        total_count:
          type: number
          example: 5
        limit:
          type: number
          example: 5
        previous:
          example:
            href: https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26
          allOf:
          - $ref: '#/components/schemas/URLCursor'
        next:
          example:
            href: https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26
          allOf:
          - $ref: '#/components/schemas/URLCursor'
      required:
      - workloads
      - total_count
      - limit
  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