Get billable calls by business ID

GET 
/v1/businesses/{businessId}/billable-calls

Returns billable call counts for one business, identified by its Hiya businessId, over the given date range, bucketed by granularity. Works for any business of yours, including one still UNDER_REVIEW or one with no billable calls in the range (total is 0). A business shut down since remains queryable for the ranges in which it belonged to you.

Path Parameters

---

businessId string<uuid>required
The ID of the business, assigned by Hiya.
Example: 9b8a1c4e-2c0f-4f3d-9a1e-7b3a2b4c6d8f

Query Parameters

---

startDate string<date>required
Start of the date range (inclusive), as
YYYY-MM-DD
. Must be on or before
endDate
.
endDate
may be at most
startDate
plus 15 months, with the day clamped to the end of the month (2026-01-31 → 2027-04-30).
Example: 2026-05-01

---

endDate string<date>required
End of the date range (inclusive), as
YYYY-MM-DD
. Must be on or after
startDate
.
endDate
may be at most
startDate
plus 15 months, with the day clamped to the end of the month (2026-01-31 → 2027-04-30).
Example: 2026-05-31

---

granularity billing_Granularity (string)
How to bucket the returned series. Defaults to
total
(no series, just the total for the range).
Possible values: [total, day, week, month]
Default value: total

Responses

200

The business's billable call counts.

Response Body

application/json

400

A query parameter is missing or invalid — startDate or endDate is absent or not a YYYY-MM-DD date, the range is reversed or longer than 15 months, or granularity is unknown.

Response Body

application/json

401

The API key is missing or invalid.

Response Body

application/json

404

The business doesn't exist, or isn't one of yours — the two are indistinguishable by design.

Response Body

application/json

500

Something went wrong on our side.

Response Body

application/json