Get the usage breakdown

What the workspace consumed and was charged over a window, grouped by one dimension per call (`by`: day, platform or keyword), in USD cents at list price, with the window's totals on every call. `range` reads a trailing window of UTC days ending today (default 30d); `month` reads one calendar month (YYYY-MM), the shape a bill or a per-customer margin is reconciled against. Keyword-days come from the daily tick and mention charges from the matches that billed, so a deleted keyword keeps its charges in the keyword rows (`keyword.removed`) while its mention counts read 0; the same numbers ride on each keyword as `stats.cost` for the running month. `totals.ledgerDebitCents` is what the wallet has debited so far for the window's days: mentions settle the morning after their day, so a window ending today lags `totals.totalCents` by the unsettled ones, and a closed month differs from it only by cumulative rounding. Rows are paged (`limit`, `offset`, `total`); a workspace may read this at most 30 times a minute through its keys and tokens together.

Authorization

AuthorizationBearer <token>

API key minted via POST /v1/api-keys (format mk_live_...)

In: header

Query Parameters

by?string

The dimension to group by: day (one row per UTC day of the window), platform, or keyword (default: the row a margin is computed from).

Default"keyword"

Value in"day" | "platform" | "keyword"

range?string

Trailing window of UTC days ending today: 7d, 30d, 90d (default 30d). Ignored when month is given.

Value in"7d" | "30d" | "90d"

month?string

A calendar month (YYYY-MM, UTC) instead of a trailing window: from its first day to its last, or to today for the running month. A future month is a 400.

Match^\d{4}-(0[1-9]|1[0-2])$

limit?integer

Rows per page, 1 to 500 (default 100). Only by=keyword can outgrow a page; a window has at most 90 days and a dozen platforms.

Default100

Range1 <= value <= 500

offset?integer|null

Skip this many rows.

Default0

Range0 <= value

Response Body

application/json

curl -X GET "https://api.mentio.dev/v1/usage/breakdown"

curl -X GET "https://api.mentio.dev/v1/usage/breakdown"

{
  "window": {
    "from": "string",
    "to": "string",
    "days": 0,
    "keywordDaysFrom": "string"
  },
  "by": "day",
  "currency": "USD",
  "totals": {
    "keywordDays": 0,
    "keywordCents": 0,
    "matchedMentions": 0,
    "billableMentions": 0,
    "mentionCents": 0,
    "totalCents": 0,
    "unclassifiedMentions": 0,
    "ledgerDebitCents": 0,
    "unattributedBillable": 0
  },
  "data": [
    {
      "key": "string",
      "label": "string",
      "keyword": {
        "id": "string",
        "term": "string",
        "removed": true
      },
      "keywordDays": 0,
      "keywordCents": 0,
      "matchedMentions": 0,
      "billableMentions": 0,
      "mentionCents": 0,
      "totalCents": 0
    }
  ],
  "total": 0
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string",
    "retryAfterSeconds": 0
  }
}

Get the usage breakdown

Authorization

Query Parameters

Response Body

200application/json

400application/json

401application/json

429application/json

application/json

application/json

application/json

application/json