Read your usage by day, number or project

Before you start

A fictional test key: tq_test_EXEMPLE.
A period: two dates in YYYY-MM-DD format.
The grouping you want: day, number, project, country or service.

Demo version. Design may change. The returned data is simulated and no production API is open.

Query usage

Call GET /usage with from and to, the bounds of the period.
Add group_by to choose how to read the data: day, number, project, country or service.
Read the provisional field. It is true when events may still arrive late: the total is then not final.

Fictional example: reading by day over a demo month.

curl "https://api.example.test/v1/usage?from=2026-10-01&to=2026-10-31&group_by=day" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Example response

Each line gives a grouping key (key), a service, a direction, a unit and a quantity. Units differ by service: duration for voice, segments for SMS. Do not add them together.

Fictional example response. Made-up values, no amount.

{
  "data": [
    { "key": "2026-10-01", "service": "voice", "direction": "outbound", "unit": "second", "quantity": 5400 },
    { "key": "2026-10-01", "service": "sms", "direction": "outbound", "unit": "segment", "quantity": 120 }
  ],
  "provisional": false
}

Points to watch

One call can generate several usage lines, for example when it has several technical segments. A line is not always a call.
A long SMS counts as several segments: the SMS quantity is a number of segments, not a number of messages.
Keep inbound and outbound apart: units and contractual rules may differ.
Billable time (billable_seconds in the call log) is neither ringing time nor necessarily talk time.
The response carries quantities. Amounts, when they exist, come from your contract and appear in the console.

Common errors

Symptom	Likely cause	What to do
400 invalid_request	Malformed date, from later than to, unknown group_by.	Use YYYY-MM-DD and one of the listed values.
Total changes between two reads	provisional is true: events are still arriving.	Read again later for a closed period.
Gap with the call log	Different units (usage seconds versus talk duration).	Compare on the same unit and direction.

What this guide does not do

It computes no cost: no price is public, everything is by custom quote.
It does not replace reconciliation with contractual documents and invoicing.
It does not claim that real volumes exist: the example is fictional.

Describe your volumes in a quote request Voice API