VoiceStudioDocs
Cloud reference

Usage

Get Usage Summary

GET
/v1/usage

Read-only ledger-derived Organization usage summary, semantically identical to the dashboard usage projection. Responses are Cache-Control no-store. An unknown or foreign organization is indistinguishable from a missing one.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Query Parameters

organization?string

Organization to read. Optional for callers with exactly one active Membership; required (organization_required) when membership is ambiguous. Never an authorization input on its own.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16

Response Body

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/usage"
json
{
  "organization_id": "stringstringstri",
  "available_credit_units": 0,
  "allowance_ends_at": "2019-08-24T14:15:22Z",
  "allowance": {
    "starts_at": "2019-08-24T14:15:22Z",
    "ends_at": "2019-08-24T14:15:22Z"
  },
  "active_reservations": 0,
  "reserved_credit_units": 0,
  "settled_credit_units": 0,
  "current_cycle": {
    "starts_at": "2019-08-24T14:15:22Z",
    "ends_at": "2019-08-24T14:15:22Z",
    "settled_events": 0,
    "settled_credit_units": 0,
    "reserved_credit_units": 0
  },
  "previous_cycle": {
    "starts_at": "2019-08-24T14:15:22Z",
    "ends_at": "2019-08-24T14:15:22Z",
    "settled_events": 0,
    "settled_credit_units": 0,
    "reserved_credit_units": 0
  }
}

List Usage Events

GET
/v1/usage/events

Cursor-paged, append-only settled usage events, newest first. Settlements and compensating Credit entries are immutable and typed as what they are. Cursors are opaque and stable across pages.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Query Parameters

organization?string

Organization to read. Optional for callers with exactly one active Membership; required (organization_required) when membership is ambiguous. Never an authorization input on its own.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16
cursor?string
Lengthlength <= 512
limit?integer
Range1 <= value <= 200
Default50

Response Body

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/usage/events"
json
{
  "items": [
    {
      "id": "stringstringstri",
      "type": "settlement",
      "job_id": "stringstringstri",
      "workflow": "string",
      "rating_policy_version": "string",
      "rated_quantity": 0,
      "rated_unit": "string",
      "credit_units": 0,
      "settled_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

Get Usage Breakdown

GET
/v1/usage/breakdown

Bounded aggregation of settled usage grouped by day, project, or workflow over a server-bounded window (92 days maximum; oversized windows are clamped and the effective window echoed). The credential dimension is reserved vocabulary and fails with the stable error code unsupported_dimension until credential attribution is recorded on Jobs.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Query Parameters

organization?string

Organization to read. Optional for callers with exactly one active Membership; required (organization_required) when membership is ambiguous. Never an authorization input on its own.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16
group_by?string
Default"day"

Value in

  • "day"
  • "project"
  • "workflow"
  • "credential"
from?string
Formatdate-time
to?string
Formatdate-time

Response Body

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/usage/breakdown"
json
{
  "dimension": "day",
  "from": "2019-08-24T14:15:22Z",
  "to": "2019-08-24T14:15:22Z",
  "groups": [
    {
      "key": "string",
      "settled_events": 0,
      "charged_credit_units": 0,
      "released_credit_units": 0
    }
  ],
  "truncated": true
}

Jobs

Previous Page

Voices

Next Page