One billing month across all nine meters

GET

/v1/usage/summary

curl --request GET \
  --url https://api.vocapable.com/v1/usage/summary \
  --header 'Authorization: Bearer <token>'

Authorizations

• HTTPBearer

Parameters

Query Parameters

period

Any of:

string

string

/^\d{4}-(0[1-9]|1[0-2])$/

null

null

Billing month, YYYY-MM

Responses

200

Successful Response

Media typeapplication/json

UsageSummary

One billing month across all nine meters, in registry order.

object

period

required

Period

string

period_start

required

Period Start

string format: date-time

period_end

required

Period End

string format: date-time

telephony_mode

required

Telephony Mode

string

Allowed values: managed byo mixed unelected

currency

Any of:

string

string

null

null

rated_total_minor

Any of:

integer

integer

null

null

billing_period_estimate

Any of:

BillingPeriodEstimate

BillingPeriodEstimate

A live, read-only estimate for the subscription’s actual billing period.

Stripe remains the source of truth for the final invoice. This value is calculated only from the current plan and usage ledger; it excludes tax, credits, discounts, proration, and any Stripe-side adjustment.

object

period_start

required

Period Start

string format: date-time

period_end

required

Period End

string format: date-time

base_price_minor

required

Base Price Minor

integer

usage_amount_minor

Any of:

integer

integer

null

null

total_amount_minor

Any of:

integer

integer

null

null

minutes_amount_minor

Any of:

integer

integer

null

null

call_fees_amount_minor

Any of:

integer

integer

null

null

volume_tier

Any of:

VolumeTierStatus

VolumeTierStatus

Where the period stands on the volume-discount ladder (ADR-0022).

Rates are minor units per minute; cumulative_period_spend_minor is the bracket basis - total period spend: base fee, extra-session fees, call fees, and minute charges. base_minute_rate_minor is the tenant’s RESOLVED starting rate (ADR-0028 d7 as amended): the open subscription_terms row’s negotiated rate when one exists, the term’s published rate otherwise - the rate the engine actually descends from. next_tier_threshold_minor/next_tier_minute_rate_minor are null once the floor is reached, and whenever the rate is pinned - a terms row snapshotting volume_ladder_applies false, or a negotiated start already below the ladder’s floor.

object

base_minute_rate_minor

required

Base Minute Rate Minor

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

current_minute_rate_minor

required

Current Minute Rate Minor

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

bracket_size_minor

required

Bracket Size Minor

integer

discount_per_bracket_minor

required

Discount Per Bracket Minor

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

floor_minute_rate_minor

required

Floor Minute Rate Minor

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

cumulative_period_spend_minor

required

Cumulative Period Spend Minor

integer

next_tier_threshold_minor

Any of:

integer

integer

null

null

next_tier_minute_rate_minor

Any of:

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

null

null

null

null

unpriced_meters

Unpriced Meters

Array<string>

Allowed values: telephony_minutes stt_audio_seconds tts_characters llm_prompt_tokens llm_cached_prompt_tokens llm_completion_tokens gpu_seconds sms_segments lookup_requests

excluded_usage_types

Excluded Usage Types

Array<string>

Allowed values: byo_carrier_usage separately_settled_prepaid_test_calls

null

null

meters

required

Meters

Array<object>

MeterUsage

One meter’s totals for the period.

The component’s headline invariant is the quantity is None vs billing == "carrier_billed" split - they are independent facts:

• quantity is None - the ledger holds no rows for this meter. Nothing was metered.
• billing == "carrier_billed" - this tenant’s own carrier bills the meter directly (CANON fact 70), so Vocapable never writes a row for it.

A tenant that switched managed→byo mid-period therefore still reports the minutes it really accrued while carrying carrier_billed, and a managed tenant with no calls reports 0, never null.

object

meter

required

Meter

string

Allowed values: telephony_minutes stt_audio_seconds tts_characters llm_prompt_tokens llm_cached_prompt_tokens llm_completion_tokens gpu_seconds sms_segments lookup_requests

billing

required

Billing

string

Allowed values: billed bundled internal carrier_billed

quantity

Any of:

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

null

null

event_count

Any of:

integer

integer

null

null

rated_amount_minor

Any of:

integer

integer

null

null

included_quantity

Any of:

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

null

null

overage_quantity

Any of:

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

null

null

Example

{
  "telephony_mode": "managed",
  "billing_period_estimate": {
    "unpriced_meters": [
      "telephony_minutes"
    ],
    "excluded_usage_types": [
      "byo_carrier_usage"
    ]
  },
  "meters": [
    {
      "meter": "telephony_minutes",
      "billing": "billed"
    }
  ]
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}