ibm-quantum Workloads API

openapi: 3.2.0
info:
  title: Qiskit Runtime Workloads 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: Workloads
paths:
  /v1/workloads:
    parameters:
    - $ref: '#/components/parameters/IBM-API-Version'
    get:
      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: include_mocks
        required: false
        in: query
        description: When true, include workloads run on mock backends. Defaults to false.
        schema:
          default: false
          type: boolean
      - 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'
        '500':
          description: Internal server error
          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:
    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
          - 'null'
          description: true if the session accepts jobs, false otherwise. Only for sessions, null for jobs
          example: 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:
          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
    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
    URLCursor:
      type: object
      properties:
        href:
          type: string
          example:
          - https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26
          - https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26
    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
    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
        value:
          type: number
          example: 0.3333
          format: float
          description: The amount of resource usage in resource units. This value is used to calculate capacity consumption.
        unit:
          type: string
          description: Unit for the value field
          example: resource_units
          enum:
          - resource_units
        status:
          type: string
          description: Status of billing data completeness. "pending" indicates billing data is still being processed. "complete" indicates billing data is final.
          example: complete
          enum:
          - pending
          - complete
        details:
          description: Per-metric breakdown of the usage. A workload can have more than one entry if the billed metric changed while it was running.
          minItems: 0
          type: array
          items:
            $ref: '#/components/schemas/UsageDetail'
      required:
      - qpu_charge_time_seconds
      - value
      - unit
    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
    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
    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
  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)