Aggregate usage over a date range
Aggregate call volume, connected minutes and spend for the organization.
Aggregate call volume, connected minutes and spend for the organization.
Backed by ONE call_records aggregate, scoped by organization_id AND
the B2B surface filter AND merged_into absent — all three are
load-bearing. The collection serves two products, so an organization
filter alone would fold native-app screening calls into a customer's
numbers, and merged orphan legs would double-count retries.
The result is cached for 60 seconds per organization and filter set. This is deliberately NOT backed by the credit ledger's spending history: that is an unbounded group over the whole organization's debits with no date filter and no cache.
Note that calls.voicemail is a dimension rather than an outcome — a
voicemail pickup is stored as no-answer plus a flag, so it is also
counted in calls.no_answer and the outcome fields do not sum to
calls.total.
Errors: 400 (to_date before from_date, or a range longer than 366
days, or an unknown group_by), 401, 403, 422, 429, 503.
Rate limit: 600 requests per minute per organization (bucket executions.list). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/usageAuthorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Query Parameters
from_dateFrom Date
Start of the window, ISO-8601 with a timezone offset. Defaults to 30 days ago.
to_dateTo Date
End of the window, ISO-8601 with a timezone offset. Defaults to now.
agent_idAgent Id
Restrict to one agent.
group_byGroup By
Breakdown to return alongside the totals: none, agent or day.
"none"organization_idOrganization Id
Optional; must match the key's organization.
Response Body
200
Call counts, connected minutes and spend, with an optional breakdown.
periodRequiredPeriod
The window these numbers cover.
callsRequiredCalls
Call counts by outcome.
minutesRequiredMinutes
Connected minutes.
costRequiredCost
Spend, with its per-service split.
groupsRequiredGroups
The same numbers split by agent or by day. Empty unless group_by was sent.
400
1000 — malformed or contradictory input. 1002 — a required parameter is missing.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
Call counts, connected minutes and spend, with an optional breakdown.