Read the ledger-backed usage and current-plan projection for a call

GET

/v1/calls/{call_id}/billing

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

One tenant-owned call’s exact recorded usage and conservative cost visibility.

A live call receives completed: false. Its live_projection is populated only for a verified managed prepaid test-call receipt; every other active lane is explicitly pending rather than a partial carrier cost. For a completed call, meters combines direct runtime attribution with a managed carrier’s attempt-linked minute row. That carrier row may still be absent while the callback is in flight; an empty list means no usage row has landed, not that a future invoice is $0.

Authorizations

• HTTPBearer

Parameters

Path Parameters

call_id

required

Call Id

string

Responses

200

Successful Response

Media typeapplication/json

CallBilling

Ledger-backed usage and a deliberately limited estimate for one call.

rated_usage_amount_minor is never an inferred cost: it stays null until every linked ledger event has a final Stripe allocation. The projection is instead the current-period marginal plan/ledger estimate - the difference between the current billing-period estimate with this call’s rows and without them. It excludes the base subscription fee, tax, credits, discounts, proration, and Stripe-side adjustments; the Stripe invoice remains authoritative.

object

call_id

required

Call Id

string

completed

required

Completed

boolean

meters

Meters

Array<object>

CallBillingMeter

The exact ledger quantity currently attributable to one finished call.

The list is intentionally sparse. An absent telephony_minutes row does not mean the carrier charged zero: carrier usage arrives through an asynchronous status callback and can appear after the call teardown. rated_amount_minor is non-null only once every event for this meter has a final Stripe per-call allocation.

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

quantity

required

Quantity

string

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

event_count

required

Event Count

integer

rated_amount_minor

Any of:

integer

integer

null

null

unrated_event_count

required

Unrated Event Count

integer

prepaid_event_count

Prepaid Event Count

integer

0

rating_status

required

Rating Status

string

Allowed values: no_usage_recorded unrated partially_rated rated prepaid_settled

rated_usage_amount_minor

Any of:

integer

integer

null

null

currency

Any of:

string

string

null

null

billing_period_start

Any of:

string

string format: date-time

null

null

billing_period_end

Any of:

string

string format: date-time

null

null

projection_status

required

Projection Status

string

Allowed values: not_available unpriced estimated

projected_marginal_usage_amount_minor

Any of:

integer

integer

null

null

projection_unpriced_meters

Projection 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

prepaid_authorization_status

Prepaid Authorization Status

string

default: not_applicable

Allowed values: not_applicable reserved captured released

prepaid_reserved_amount_minor

Any of:

integer

integer

null

null

prepaid_captured_amount_minor

Any of:

integer

integer

null

null

live_projection

Any of:

LiveCallBillingProjection

LiveCallBillingProjection

A bounded elapsed-time estimate for the one live lane with a frozen platform rate.

It is available only while a platform-managed, prepaid, campaignless test call holds a durable authorization. connected_at is the redeemed live-session receipt’s trusted start, while the carrier’s terminal callback remains the authority for the actual debit. BYO carrier prices and ordinary production-call carrier amounts are intentionally absent.

object

status

required

Status

string

Allowed values: not_available estimated

basis

Any of:

string

string

Allowed value: managed_test_call_prepaid

null

null

connected_at

Any of:

string

string format: date-time

null

null

projected_through

Any of:

string

string format: date-time

null

null

elapsed_seconds

Any of:

integer

integer

null

null

projected_billable_seconds

Any of:

integer

integer

null

null

projected_amount_minor

Any of:

integer

integer

null

null

platform_rate_per_minute_minor

Any of:

string

string

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

null

null

currency

Any of:

string

string

null

null

null

null

Example

{
  "meters": [
    {
      "meter": "telephony_minutes",
      "prepaid_event_count": 0
    }
  ],
  "rating_status": "no_usage_recorded",
  "projection_status": "not_available",
  "projection_unpriced_meters": [
    "telephony_minutes"
  ],
  "prepaid_authorization_status": "not_applicable",
  "live_projection": {
    "status": "not_available",
    "basis": "managed_test_call_prepaid"
  }
}

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": {}
    }
  ]
}