Get usage and balance
Shows whether tracking is stopped or the balance is low. Also returns the prepaid balance (ledger total, pending mention charges, and the effective balance that decides pausing), daily spend and days left, running and paused keywords, and matches today and over 30 days. Pricing is $0.008 per matched mention, relevant or not, and $5 a month per active keyword, charged daily.
Authorization
bearerAuth An API key from POST /v1/api-keys. Keys start with ref_.
In: header
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/usage"{ "balance": { "cents": 0, "pendingCents": 0, "effectiveCents": 0, "currency": "USD" }, "burn": { "perDayCents": 0, "daysLeft": 0 }, "keywords": { "active": 0, "paused": 0, "capped": 0, "limit": 0, "dayCents": 0 }, "mentions": { "today": 0, "last30d": 0 }, "stopped": true, "lowBalance": true, "lastTopUpAt": "string"}Get the usage breakdown
Returns what the workspace used and was charged over a period, in US cents at list price. Each call groups rows by one `by` value, day, platform or keyword, and always includes the totals. `range` reads the past UTC days up to today (30d by default). `month` reads one calendar month (YYYY-MM), which is what you match against a bill or a per-client margin. Keyword-days come from the daily run and mention charges from billed matches. So a deleted keyword keeps its charges in the keyword rows (`keyword.removed`), while its mention counts show 0. Each keyword carries the same numbers for the current month as `stats.cost`. `totals.ledgerDebitCents` is what the balance has been debited so far for the period's days. Mentions settle the morning after, so a period ending today is below `totals.totalCents` by the unsettled ones, and a finished month differs only by cumulative rounding. Rows come in pages (`limit`, `offset`, `total`). A workspace can call this 30 times a minute across all its keys and tokens.
Create a view
Saves a named mention filter. It uses the same fields as GET /v1/mentions, where a list matches any value, a `not` list matches none, and all conditions are joined by AND. `anyOf` adds groups of such conditions, at least one of which must match. An empty filter shows all mentions. Nothing is stored ahead of time, so a view shows whatever matches when you read it.