Get usage

Returns the workspace's plan, its billable events in the current usage window and a day-by-day breakdown: the numbers on Workspace → Usage & Billing. Usage counts every audience in the workspace together.

There is no audience in this request, so the workspace comes from the key. An audience key reads the workspace that owns its audience. An account key reads its owner's own workspace, unless an X-Team-Id header names another workspace they belong to.

Any member can read it, Viewer included. Changing the plan needs an Admin, in the app.

Keys: an account key or an audience key. Getting started explains both kinds.

Response

Prop	Type	Notes
`plan`	`BillingPlanDto`	The current plan: `id` (`free`, or a size such as `250k`), `name` (`Free` or `Growth`), `monthly` and `yearly` prices in US dollars (0 on Free) and `eventsLimit`, the monthly allowance that applies. A paid plan keeps the allowance it was bought with.
`plans`	`BillingPlanDto[]`	Every plan on offer, in the same shape, smallest allowance first.
`periodStart`	`string`	Start of the current usage window, ISO 8601. On Free it is the calendar month in UTC. On a paid plan it is one month counted from the billing day, yearly billing included.
`periodEnd`	`string`	End of the window, not included.
`eventsUsed`	`number`	Billable events in the window, across every audience in the workspace. Session ends, scroll events and link clicks are recorded but not billed.
`eventsLimit`	`number`	The allowance for the window, the same as `plan.eventsLimit`.
`perDay`	`BillingUsagePointDto[]`	One `{ date, count }` per UTC day of the window, oldest first. Days still to come are included as 0.
`exceeded`	`boolean`	`true` once `eventsUsed` is over `eventsLimit`. Events are still recorded, up to the hard stop.
`stopped`	`boolean`	`true` once usage reaches the hard stop: 3 times the allowance on plans of up to 1,000,000 events, 1.5 times above that. New events are dropped until the window resets or the plan grows, so check this first.
`nearLimit`	`boolean`	`true` from 90% of the allowance, and it stays `true` once over.
`exceededAt`	`string`	When the workspace was first seen over its allowance in this window, as an ISO timestamp, or `null`. The first usage read that sees the overage records it.
`dataCutoff`	`string`	When over the allowance: the time of the first event past it, otherwise `null`. Charts, analytics reads and people queries, in the app and through the API, show nothing after this moment until the window resets or the plan grows. The events after it are kept.
`subscriptionStatus`	`string`	The status of the paid subscription, or `null` when there is none.
`cancelAtPeriodEnd`	`boolean`	`true` when the plan has been cancelled and ends with the current billing period.

Request

curl 'https://app.spreelytics.com/api/v1/spreelytics/billing/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch('https://app.spreelytics.com/api/v1/spreelytics/billing/usage', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const data = await res.json();

import requests

res = requests.get(
    "https://app.spreelytics.com/api/v1/spreelytics/billing/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

Response

{
  "plan": {
    "id": "string",
    "name": "string",
    "monthly": 0,
    "yearly": 0,
    "eventsLimit": 0
  },
  "plans": [
    {
      "id": "string",
      "name": "string",
      "monthly": 0,
      "yearly": 0,
      "eventsLimit": 0
    }
  ],
  "periodStart": "string",
  "periodEnd": "string",
  "eventsUsed": 0,
  "eventsLimit": 0,
  "perDay": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "exceeded": true,
  "stopped": true,
  "nearLimit": true,
  "exceededAt": "string",
  "dataCutoff": "string",
  "subscriptionStatus": "string",
  "cancelAtPeriodEnd": true
}

PreviousGet plan entitlement Next Get the event catalog

Get usage

Response

See your own numbers today.

Tell us what you need.