Roark Usage API
The Usage API from Roark — 1 operation(s) for usage.
The Usage API from Roark — 1 operation(s) for usage.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/roark:roark-usage-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Roark Analytics Usage API
description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
version: 1.0.0
servers:
- description: Production
url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Usage
paths:
/v1/usage:
get:
responses:
'200':
description: The usage & cost report for the window
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/UsageReport'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1Usage
tags:
- Usage
summary: Get usage & cost
description: Report billable usage and cost for the organization over a time window, broken down by project (highest spend first). Pass `from`/`to` as ISO 8601 timestamps; optionally pass `projectId` to scope the report to one project. Amounts are billable spend only (what we absorb is never included). Authenticated by either an organization API key with the `usage:read` permission (any project in the organization), or a project API key with the `billing:read` permission (that key's own project only; any other `projectId` is a 403).
parameters:
- in: query
name: from
schema:
type: string
format: date-time
description: Start of the window (inclusive), ISO 8601.
example: '2026-09-01T00:00:00Z'
required: true
- in: query
name: to
schema:
type: string
format: date-time
description: End of the window (exclusive), ISO 8601. Must be after `from`, and the window may not exceed 366 days.
example: '2026-10-01T00:00:00Z'
required: true
- in: query
name: projectId
schema:
type: string
format: uuid
description: Limit the report to a single project. Omit for the whole organization.
required: false
components:
schemas:
ErrorResponse:
type: object
properties:
type:
type: string
enum:
- validation
- authentication
- forbidden
- not_found
- conflict
- payment_required
- rate_limit
- internal
description: The error type category
examples:
- validation
- authentication
code:
type: string
description: Machine-readable error code identifier
examples:
- invalid_parameter
- missing_required_field
- unauthorized
message:
type: string
description: Human-readable error message
examples:
- The request was invalid
- Authentication required
param:
type: string
description: The parameter that caused the error (if applicable)
examples:
- email
- user_id
details:
description: Additional error context information
required:
- type
- code
- message
UsageProjectCost:
type: object
properties:
projectId:
type: string
format: uuid
projectName:
type:
- string
- 'null'
description: Null only if the project no longer exists in this organization.
amountUsdMicros:
type: integer
description: Billable spend in integer micro-dollars (1,000,000 = $1). The exact value.
amountUsd:
type: number
description: The same billable spend in US dollars. For display; use amountUsdMicros to reconcile.
breakdown:
type: array
items:
$ref: '#/components/schemas/UsageCostType'
description: This project's spend split by cost type, highest first. Sums to amountUsdMicros.
required:
- projectId
- projectName
- amountUsdMicros
- amountUsd
- breakdown
UsageReport:
type: object
properties:
from:
type: string
description: The resolved window start, echoed back as ISO 8601.
to:
type: string
description: The resolved window end, echoed back as ISO 8601.
currency:
type: string
const: usd
totalUsdMicros:
type: integer
description: Total billable spend across the organization (or the single project) in micro-dollars.
totalUsd:
type: number
description: The same total in US dollars.
projects:
type: array
items:
$ref: '#/components/schemas/UsageProjectCost'
description: Per-project billable spend, highest first. Only projects with spend in the window appear.
required:
- from
- to
- currency
- totalUsdMicros
- totalUsd
- projects
UsageCostType:
type: object
properties:
source:
type: string
enum:
- SIM_PLATFORM_FEE
- SIM_TTS
- SIM_STT
- SIM_LLM
- SIM_TELEPHONY
- METRIC
- TRANSCRIPTION
- INTERNAL_LLM
- INTERNAL_STT
- PHONE_NUMBER
description: The cost source, e.g. SIM_PLATFORM_FEE, SIM_LLM, SIM_TTS, SIM_STT, SIM_TELEPHONY, METRIC, or TRANSCRIPTION. These are the granular sources behind the Billing screen categories (SIM_* roll up into "Simulation").
surface:
type: string
enum:
- SIMULATION
- POST_CALL
description: Whether this cost came from a SIMULATION or a production call (POST_CALL).
amountUsdMicros:
type: integer
description: Billable spend for this type, in micro-dollars.
amountUsd:
type: number
description: The same figure in US dollars.
required:
- source
- surface
- amountUsdMicros
- amountUsd
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT