IBM Quantum Usage-Aware Job Submission

arazzo: 1.0.1
info:
  title: IBM Quantum Usage-Aware Job Submission
  summary: Check instance usage and remaining limit before submitting a job, skipping submission when the limit is reached.
  description: >-
    A budget-guarded submission flow. The workflow reads the current instance
    usage to see how much QPU time has been consumed against the limit and
    branches: when the usage limit has not been reached it submits a primitive
    job, and when the limit is already reached it ends without spending more
    capacity. Each request inlines its bearer token, Service-CRN, and
    IBM-API-Version headers so the flow can be read and executed without opening
    the underlying OpenAPI descriptions.
  version: 1.0.0
sourceDescriptions:
- name: instancesApi
  url: ../openapi/ibm-quantum-instances-api-openapi.yml
  type: openapi
- name: jobsApi
  url: ../openapi/ibm-quantum-jobs-api-openapi.yml
  type: openapi
workflows:
- workflowId: usage-aware-job-submission
  summary: Submit a job only when the instance usage limit has not been reached.
  description: >-
    Reads instance usage, then submits a primitive job only if the usage limit
    has not yet been reached.
  inputs:
    type: object
    required:
    - accessToken
    - serviceCrn
    - apiVersion
    - backend
    - programId
    - params
    properties:
      accessToken:
        type: string
        description: IBM Cloud IAM bearer token used in the Authorization header.
      serviceCrn:
        type: string
        description: IBM Cloud Service CRN identifying the Qiskit Runtime instance.
      apiVersion:
        type: string
        description: API version date sent in the IBM-API-Version header (e.g. 2026-03-15).
      backend:
        type: string
        description: Name of the backend on which to run the program.
      programId:
        type: string
        description: ID of the primitive program to execute.
      params:
        type: object
        description: The primitive input params object.
  steps:
  - stepId: getInstanceUsage
    description: >-
      Read the instance's current usage period, including consumed seconds and
      whether the usage limit has been reached.
    operationId: get_usage
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: Service-CRN
      in: header
      value: $inputs.serviceCrn
    - name: IBM-API-Version
      in: header
      value: $inputs.apiVersion
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      usageConsumedSeconds: $response.body#/usage_consumed_seconds
      usageLimitReached: $response.body#/usage_limit_reached
    onSuccess:
    - name: limitReached
      type: end
      criteria:
      - context: $response.body
        condition: $.usage_limit_reached == true
        type: jsonpath
    - name: hasCapacity
      type: goto
      stepId: submitJob
      criteria:
      - context: $response.body
        condition: $.usage_limit_reached != true
        type: jsonpath
  - stepId: submitJob
    description: >-
      Submit the primitive job now that the instance still has usage capacity.
    operationId: create_job
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: Service-CRN
      in: header
      value: $inputs.serviceCrn
    - name: IBM-API-Version
      in: header
      value: $inputs.apiVersion
    requestBody:
      contentType: application/json
      payload:
        program_id: $inputs.programId
        backend: $inputs.backend
        params: $inputs.params
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      jobId: $response.body#/id
  outputs:
    usageConsumedSeconds: $steps.getInstanceUsage.outputs.usageConsumedSeconds
    jobId: $steps.submitJob.outputs.jobId