Usage & Cost Reporting

Every bit of billable work in Roark (simulations, metric evaluations, transcription) is attributed to the project that incurred it. You can read that attribution three ways:

Billing screen (Settings → Billing): a per-project and per-type spend breakdown for the current billing period.
CSV export: the “Export CSV” button on that breakdown downloads exactly what you see, grouped by project or by type.
API (GET /v1/usage): the same per-project figures over a date range you choose, for feeding a warehouse, a finance report, or a per-team chargeback.

For a single call or simulation run, the call page’s Cost tab and the run report’s Cost section show what it cost, and the API exposes the same figures (see Per-call and per-run cost). This page covers who can see spend, and the API.

Who can see spend

Billing is organization-wide financial data, so no project role includes it, not even project Owner or Admin. You can see the Billing screen, the CSV export, and the per-call and per-run cost views if you are:

an organization Owner or Admin, or
a member an Owner has granted billing access: in Settings → Project → Members, open the member’s Data access and turn on View billing. The grant applies to the whole organization (the Billing screen shows every project’s spend), and it is read-only. Organization settings stay hidden.

Authentication

GET /v1/usage accepts two credentials. Pick the narrower one that does the job.

Credential	Permission	Reads
Project API key	`billing:read`	That key’s own project only.
Organization API key	`usage:read`	Every project in the organization.

Project API key (least privilege)

For a team that reports its own spend, use a project key that carries billing:read. It reads only its own project: leave out projectId (or pass the key’s own project), and any other projectId returns 403. A key that holds only billing:read can read spend and nothing else. Create one in Settings → Project → API keys: choose Custom, set every row to No Access if spend is all you need, and turn on Spend. The Spend switch only appears for people who can see billing (see above), and the API refuses billing:read on a key minted by anyone else, so a project admin cannot give themselves spend through a key.

Organization API key

For a finance or warehouse job that needs every project, use an Organization API key (the same credential family used for org provisioning) that carries usage:read. An org Owner or Admin creates one under Settings → Organization → API keys; new keys get the full organization permission set, so they include usage:read.

Cost visibility is a deliberately separate permission from project access. If you are using an organization key created before usage reporting launched, re-mint it so it carries usage:read; an older key returns 403 on this endpoint.

Endpoint

GET https://api.roark.ai/v1/usage

Query parameters

Parameter	Required	Description
`from`	yes	Start of the window (inclusive), ISO 8601. Example: `2026-09-01T00:00:00Z`.
`to`	yes	End of the window (exclusive), ISO 8601. Must be after `from`, and the window may not exceed 366 days.
`projectId`	no	Limit the report to a single project. Omit for the whole organization.

Example request

import Roark from '@roarkanalytics/sdk'

const client = new Roark({ bearerToken: process.env.ROARK_ORG_API_KEY })

const usage = await client.usage.get({
  from: '2026-09-01T00:00:00Z',
  to: '2026-10-01T00:00:00Z',
  // projectId: '7b3c0a1e-1111-2222-3333-444455556666', // scope to one project
})

console.log(usage.data.totalUsd)

roark usage get \
  --from 2026-09-01T00:00:00Z \
  --to 2026-10-01T00:00:00Z
# add --project-id <uuid> to scope to one project

curl -s "https://api.roark.ai/v1/usage?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $ROARK_ORG_API_KEY"

curl -s "https://api.roark.ai/v1/usage?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z&projectId=7b3c0a1e-1111-2222-3333-444455556666" \
  -H "Authorization: Bearer $ROARK_ORG_API_KEY"

curl -s "https://api.roark.ai/v1/usage?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $ROARK_PROJECT_API_KEY"

Example response

{
  "data": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-10-01T00:00:00.000Z",
    "currency": "usd",
    "totalUsdMicros": 1234567,
    "totalUsd": 1.234567,
    "projects": [
      {
        "projectId": "7b3c0a1e-1111-2222-3333-444455556666",
        "projectName": "Payments (prod)",
        "amountUsdMicros": 900000,
        "amountUsd": 0.9,
        "breakdown": [
          { "source": "SIM_PLATFORM_FEE", "surface": "SIMULATION", "amountUsdMicros": 600000, "amountUsd": 0.6 },
          { "source": "SIM_LLM", "surface": "SIMULATION", "amountUsdMicros": 300000, "amountUsd": 0.3 }
        ]
      },
      {
        "projectId": "9f1a2b3c-aaaa-bbbb-cccc-ddddeeeeffff",
        "projectName": "Support line",
        "amountUsdMicros": 334567,
        "amountUsd": 0.334567,
        "breakdown": [
          { "source": "METRIC", "surface": "POST_CALL", "amountUsdMicros": 334567, "amountUsd": 0.334567 }
        ]
      }
    ]
  }
}

Response fields

totalUsdMicros / totalUsd: total billable spend across the organization (or the single project, when projectId is set) over the window. The total is the sum of projects.
projects[]: per-project billable spend, highest first. Only projects with spend in the window appear.
projectName: the project’s current name, or null if the project no longer exists.
projects[].breakdown[]: that project’s spend split by cost type, highest first, summing to the project’s amountUsdMicros. Each entry has a source and a surface. source is the granular cost source (SIM_PLATFORM_FEE, SIM_LLM, SIM_TTS, SIM_STT, SIM_TELEPHONY, METRIC, TRANSCRIPTION); the SIM_* sources are what the Billing screen groups under “Simulation”. surface is SIMULATION or POST_CALL (a production call). Roll these up however your report needs.
Micros vs dollars: amountUsdMicros is the exact, canonical integer (1,000,000 = $1, the unit the billing ledger stores). Use it to sum and reconcile against an invoice. amountUsd is the same figure as a convenience float for display.

Amounts are billable spend only. Internal costs Roark absorbs on your behalf are never included, so these figures match what you are charged.

Errors

Status	Meaning
`400`	Missing or invalid `from`/`to`, or a window wider than 366 days.
`401`	Missing or invalid API key.
`403`	The organization key does not carry `usage:read`, the project key does not carry `billing:read`, or a project key asked for another project’s `projectId`.

Paging longer histories

The 366-day ceiling keeps a single request bounded. To report across a longer period, page the window month by month (or quarter by quarter) and sum the totalUsdMicros from each response.

Per-call and per-run cost

Spend is attributed to the call and to the simulation run that incurred it, not only to the project and window. Both endpoints need a project API key with billing:read, and read only that key’s project.

One call

GET https://api.roark.ai/v1/call/{callId}/cost

The billable spend for one call, split by cost type, with every cost line behind it. A simulated call includes what its simulation spent before the call connected.

{
  "data": {
    "callId": "3f2c9d1e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "currency": "usd",
    "totalUsdMicros": 412000,
    "totalUsd": 0.412,
    "breakdown": [
      { "source": "SIM_PLATFORM_FEE", "surface": "SIMULATION", "amountUsdMicros": 250000, "amountUsd": 0.25, "quantity": 5 },
      { "source": "METRIC", "surface": "SIMULATION", "amountUsdMicros": 162000, "amountUsd": 0.162, "quantity": 10.8 }
    ],
    "items": [
      {
        "eventId": "evt_8d1c...",
        "source": "METRIC",
        "surface": "SIMULATION",
        "amountUsdMicros": 81000,
        "amountUsd": 0.081,
        "quantity": 5.4,
        "quantityUnit": "MINUTES",
        "provider": null,
        "model": null,
        "simulationJobId": "a1b2c3d4-0000-4000-8000-000000000001",
        "metricDefinitionId": "b2c3d4e5-0000-4000-8000-000000000002",
        "metricCollectionJobId": "c3d4e5f6-0000-4000-8000-000000000003",
        "occurredAt": "2026-10-20T03:14:15.000Z"
      }
    ]
  }
}

A call graded twice carries one METRIC line per grading pass; metricCollectionJobId tells them apart.

One simulation run

GET https://api.roark.ai/v1/simulation/plan/job/{jobId}/cost

The billable spend for one simulation run (run plan job): totals by cost type, and the spend of each simulated call. Safe to call while the run is in progress; totals reflect what has been recorded so far. For a call’s line items, call the per-call endpoint with its conversationId.

{
  "data": {
    "jobId": "7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f",
    "currency": "usd",
    "totalUsdMicros": 2060000,
    "totalUsd": 2.06,
    "breakdown": [
      { "source": "SIM_PLATFORM_FEE", "surface": "SIMULATION", "amountUsdMicros": 1250000, "amountUsd": 1.25, "quantity": 25 },
      { "source": "METRIC", "surface": "SIMULATION", "amountUsdMicros": 810000, "amountUsd": 0.81, "quantity": 54 }
    ],
    "calls": [
      {
        "conversationId": "3f2c9d1e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "simulationJobId": "a1b2c3d4-0000-4000-8000-000000000001",
        "amountUsdMicros": 412000,
        "amountUsd": 0.412,
        "breakdown": [
          { "source": "SIM_PLATFORM_FEE", "surface": "SIMULATION", "amountUsdMicros": 250000, "amountUsd": 0.25, "quantity": 5 },
          { "source": "METRIC", "surface": "SIMULATION", "amountUsdMicros": 162000, "amountUsd": 0.162, "quantity": 10.8 }
        ]
      }
    ]
  }
}

conversationId is the call id for voice runs (the chat id for chat runs). It is null for costs incurred before the conversation existed; join those on simulationJobId.

Errors

Status	Meaning
`401`	Missing or invalid API key.
`403`	The key does not carry `billing:read`.
`404`	No such call or run in the key’s project.

Getting Started

Simulations

Observability

Metrics

Autoimprove

Recipes

Integrations

Enterprise

Resources

Usage & Cost Reporting

Who can see spend

Authentication

Project API key (least privilege)

Organization API key

Endpoint

Query parameters

Example request

Example response

Response fields

Errors

Paging longer histories

Per-call and per-run cost

One call

One simulation run

Errors