Qiskit Runtime Analytics API
Usage analytics and active-workload reporting for a Qiskit Runtime instance. Powers FinOps and plan-utilization tracking against Open, Pay-As-You-Go, Flex, and Premium minute pools.
Usage analytics and active-workload reporting for a Qiskit Runtime instance. Powers FinOps and plan-utilization tracking against Open, Pay-As-You-Go, Flex, and Premium minute pools.
openapi: 3.0.0
info:
title: Qiskit Runtime 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
tags:
- name: Analytics
- name: Workloads
paths:
/v1/workloads:
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
parameters:
- $ref: '#/components/parameters/IBM-API-Version'
/v1/analytics/usage:
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
parameters:
- $ref: '#/components/parameters/IBM-API-Version'
/v1/analytics/usage_grouped:
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
parameters:
- $ref: '#/components/parameters/IBM-API-Version'
/v1/analytics/usage_grouped_by_date:
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
parameters:
- $ref: '#/components/parameters/IBM-API-Version'
/v1/analytics/filters:
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
parameters:
- $ref: '#/components/parameters/IBM-API-Version'
components:
schemas:
BackendFilter:
type: object
properties:
name:
type: string
example: simulator
required:
- name
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
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
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
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
GetAnalyticsUsageGroupedResponse:
type: object
properties:
data:
description: Data
type: array
items:
$ref: '#/components/schemas/GetAnalyticsUsageGroupedResponseData'
required:
- data
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
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
InstanceFilter:
type: object
properties:
id:
type: string
example: 'crn:v1:staging:public:quantum-computing:region:a/account:'
deleted:
type: boolean
required:
- id
- deleted
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
PlanFilter:
type: object
properties:
name:
type: string
example: premium
required:
- name
SubscriptionFilter:
type: object
properties:
id:
type: string
example: 7f666d17-7893-47d8-bf9d-2b2389fc4dfc
name:
type: string
example: premium
required:
- id
- name
URLCursor:
type: object
properties:
href:
type: string
example:
- https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26
- https://api.
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ibm-quantum/refs/heads/main/openapi/ibm-quantum-runtime-analytics-openapi.yml