Usage

What your tenants used: every call and its billable time, recordings, and stored recordings per day, from Calloop's usage ledger; and, once the operator has put you on a price plan, what each costs you (charges); on your own trunks with carrier sheets, what your carrier charges you (carrierCost). Every total adds up to the groups and to the records under it, every call record names its call, and every charge says how it was worked out.

Method	Path	Query	Response
GET	/v1/usage	from, to, group_by, utc_offset_minutes, tenant_ref	{ from, to, groupBy, utcOffsetMinutes, totals, groups: [{ <group key>, … }] }
GET	/v1/usage/records	from, to, kind, page, limit, tenant_ref	{ from, to, page, limit, total, records: [{ id, kind, … }] }
GET	/v1/tenants/{t}/usage	from, to, group_by, utc_offset_minutes	as /v1/usage, one tenant
GET	/v1/tenants/{t}/usage/records	from, to, kind, page, limit	as /v1/usage/records, one tenant

• from / to: ISO 8601; default the last 30 days; at most 400 days. A record belongs to the window by when it counts: a call's end, a recording's completion, a stored day's start (UTC).

• group_by: day (the default; in utc_offset_minutes, a fixed offset), tenant (/v1/usage only), line, direction, channel, trunk_owner. Each group carries its key — day (YYYY-MM-DD), tenantRef, lineAddress + channel, direction, channel, trunkOwner — and the same fields as totals:

  Field	Meaning
  calls, answeredCalls	Ended calls, and those answered (by an agent or the IVR)
  callSeconds	Billable time: answer to end, summed over calls (0 for unanswered ones)
  inboundSeconds, outboundSeconds	The same, by direction
  recordings, recordingSeconds	Completed recordings and their length
  storageByteDays	Recordings held, in bytes, summed per day
  agentDays, lineDays, planDays	Agents and lines that existed, summed per closed day (UTC), and days on a plan — what monthly fees are charged from, a day (1/30 of the month) at a time
  charges	{ amount, currency, priced, unpriced }: what you're charged for it (6 decimals; an invoice rounds its total), how many records are priced, and how many your plan couldn't price
  tenantCharges	The same for what you charge your tenants (Pricing your tenants); the only money a session for one tenant sees
  carrierCost	The same for what your own carriers charge you: calls on your own trunks that have carrier sheets (priced and unpriced count only those)

• Records (kind: CALL, RECORDING, STORAGE, and per closed day PLAN_DAY, AGENT_DAY, LINE_DAY, TENANT_DAY with a count, unit COUNT; a plan day isn't a tenant's: its tenantRef is null; a tenant day is an active tenant's day on your price plan, priced only into tenantCharges and counted in no total). The kind filter takes only CALL, RECORDING or STORAGE; the day records appear only in an unfiltered list. Newest first, limit 1…500 (default 50): occurredAt, tenantRef, callId, channel, lineAddress, direction, trunkOwner (PLATFORM: a trunk the operator provides; CONSUMER: your own; null for WhatsApp), remotePrefix (the customer's number, first 8 digits only), answered, startedAt, answeredAt, endedAt, quantity with its unit (SECOND, or BYTE_DAY for storage), storageTier (HOT / COLD), and charges: null until it is priced (no price plan, or a few seconds after it is recorded), else { status, amount, currency, billedQuantity, rate, how } — status RATED, or NO_RATE with how.reason (no rate for the number, nothing in the plan for it); billedQuantity the seconds billed after the blocks (or byte-days); rate per minute (per GB-month for storage); how the plan and the sheet row that priced it (prefix, destination, initialSeconds / incrementSeconds, markupPercent and baseRate when the price is the carrier's plus a markup). tenantCharges and carrierCost take the same shape: null when nothing prices the record on them.

• A call is recorded about a minute after it ends (once the provider's own timing is in), once. Records are kept when the call is deleted or the customer erased (they hold no full number), and when a tenant is deleted.

• A dashboard session for one tenant sees only that tenant: /v1/usage is its tenant's usage, and any other tenant_ref is 404. It never sees charges or carrierCost (what you pay is yours to show or not).

• How a call is priced: by the number dialled (outbound) or the line's own number (inbound), the longest matching prefix in force when the call started; billed in blocks — the first initialSeconds, then incrementSeconds (60/60 bills 61 s as 120 s, 1/1 as 61 s); plus a connection fee on answered calls when the row has one.