Skip to main content
GET
/
v1
/
billing
/
usage
Usage
curl --request GET \
  --url https://api.example.com/v1/billing/usage \
  --header 'Authorization: <authorization>'

​
Overview

Returns a detailed breakdown of API usage — investigations, events ingested, and API calls — for the current and optionally previous billing periods. Use this to build usage dashboards or track quota burn rate. Required role: admin

​
Request headers

​
Authorization
string
required
JWT Bearer token. Format: Bearer <your-jwt>.

​
Query parameters

​
period
string
Billing period to query. One of: current, previous. Default: current.
​
groupBy
string
Aggregate usage by dimension. One of: day, week. Default: no grouping.

​
Response

Returns 200 OK. 
{
  "period": "current",
  "start": "2024-04-01T00:00:00Z",
  "end": "2024-05-01T00:00:00Z",
  "totals": {
    "investigations": 142,
    "events": 8420,
    "apiCalls": 14230
  },
  "limits": {
    "investigations": 500,
    "events": 10000
  },
  "dailyBreakdown": [
    {
      "date": "2024-04-01",
      "investigations": 12,
      "events": 820,
      "apiCalls": 1200
    },
    {
      "date": "2024-04-02",
      "investigations": 8,
      "events": 430,
      "apiCalls": 980
    }
  ]
}
FieldTypeDescription
periodstringPeriod queried: current or previous
totals.investigationsintegerTotal investigations run in this period
totals.eventsintegerTotal events ingested in this period
totals.apiCallsintegerTotal authenticated API calls in this period
limitsobjectPlan quota limits for this period
dailyBreakdownarrayPer-day breakdown when groupBy=day is set

​
Error responses

StatusError codeDescription
401unauthorizedMissing or invalid JWT
403forbiddenCaller lacks admin role

​
Examples

curl "https://api.causeflow.ai/v1/billing/usage?period=current&groupBy=day" \
  -H "Authorization: Bearer eyJhbGc..."

Credits

View credit balance for overage coverage

Subscription

Upgrade your plan before quota exhaustion