Get the usage breakdown

gethttps://api.mentio.dev/v1/usage/breakdown

Report what the workspace was charged over a window at list price, grouped by one dimension (by).

Rows are paged; the window's totals come on every call.
30 reads a minute per workspace.

See Cost per keyword.

Authentication

AuthorizationBearer <token>Required

An API key (mk_live_...) from the dashboard or an OAuth access token. See Authentication.

Query parameters

bystringOptional

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

One ofdayplatformkeywordgroupDefault"keyword"

rangestringOptional

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

One of7d30d90d

monthstringOptional

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.

fromstringOptional

First UTC day of a custom window, YYYY-MM-DD, inclusive; with to (default today). At most 366 days. Wins over range and month.

tostringOptional

Last UTC day of a custom window, YYYY-MM-DD, inclusive; never after today. Needs from.

keywordIdsarray<string>nullableOptional

Only these keywords (kw_...), deleted ones included. Repeatable, or comma-separated.

0 to 30 items

groupIdsarray<string>nullableOptional

Only these groups (grp_...): a keyword-day by the group it was metered under, a mention or a comment by its keyword's group as it is now. Repeatable, or comma-separated.

0 to 30 items

platformsarray<string>Optional

Only these platforms. A keyword-day belongs to no platform, so with this filter the keyword line reads 0 and only mentions and comments count. Repeatable, or comma-separated.

0 to 20 items

+Show 18 enum values

blueskyhackernewsgithubstackoverflowdevtoredditxyoutubenewslinkedintiktokinstagramfacebookappstoregoogleplaytrustpilotgooglemapsrss

notKeywordIdsarray<string>nullableOptional

Never these keywords (kw_...). Repeatable, or comma-separated.

0 to 30 items

notGroupIdsarray<string>nullableOptional

Never keywords of these groups (grp_...). Repeatable, or comma-separated.

0 to 30 items

notPlatformsarray<string>Optional

Never mentions or comments from these platforms; keyword-days, which belong to no platform, still count. Repeatable, or comma-separated.

0 to 20 items

+Show 18 enum values

blueskyhackernewsgithubstackoverflowdevtoredditxyoutubenewslinkedintiktokinstagramfacebookappstoregoogleplaytrustpilotgooglemapsrss

limitintegerOptional

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.

Default1001 to 500

offsetintegernullableOptional

Skip this many rows.

Default00 to ∞

Response

200The window's totals and one page of rows for the dimension

windowobjectRequired

The window the report covers, in UTC days.

+Show 4 properties

fromstringRequired

First day, YYYY-MM-DD, inclusive, UTC.

tostringRequired

Last day, inclusive: today for a trailing window or the running month.

daysintegerRequired

Length of the window in days.

0 to ∞

keywordDaysFromstringnullableRequired

The first day of the window with a recorded keyword count, or null when there is none. Earlier days carry keywordDays: null.

bystringRequired

The dimension the rows are grouped by.

One ofdayplatformkeywordgroup

filteredbooleanRequired

true when keywordIds, groupIds or platforms narrowed the report: totals and rows count only what passes them, except totals.ledgerDebitCents, which is the whole workspace's.

currencystringRequired

Every amount is in USD cents.

One ofUSD

totalsobjectRequired

The whole window as one line, the same for every dimension.

+Show 11 properties

keywordDaysintegerRequired

Keyword-days metered in the window.

0 to ∞

keywordCentsintegerRequired

The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total.

matchedMentionsintegerRequired

Matches recorded in the window, relevant or not.

0 to ∞

billableMentionsintegerRequired

Of the matches billed in the window (every scored match, relevant or not), the ones in this group.

0 to ∞

unclassifiedMentionsintegerRequired

Matches in the window that are never charged: not scored yet, classification failed, or a free review from a new app's look-back. Every other match is charged, on the mentions or comments line.

0 to ∞

mentionCentsintegerRequired

The billed mentions at $0.008 each, rounded once on the total.

billableCommentsintegerRequired

Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace.

0 to ∞

commentCentsintegerRequired

The billed comments at $0.008 each, rounded once on the total.

totalCentsintegerRequired

keywordCents plus mentionCents plus commentCents.

ledgerDebitCentsintegerRequired

What the ledger has debited for the window's days, by the day each debit settled, for the whole workspace whatever the filters. Lags totalCents by unsettled mentions; see The ledger.

unattributedBillableintegerRequired

Billed mentions whose match row is gone (deleted keyword), so no platform or keyword row claims them; charged all the same. Comments never are (by=group puts a deleted keyword's comments on the no-group row).

0 to ∞

dataarray<object>Required

by=day: chronological. by=platform and by=keyword: most expensive first, then most matched, deleted keywords included.

+Show 13 properties

keystringRequired

The row's key: the UTC day (YYYY-MM-DD) for by=day, the platform for by=platform, the keyword id for by=keyword, the group id for by=group.

labelstringRequired

Readable name: the keyword term or the group name, otherwise the key.

keywordobjectnullableRequired

by=keyword only; null otherwise.

+Show 3 properties

idstringRequired

Keyword id (kw_...); a deleted keyword keeps its id here.

termstringRequired

The term as it was last metered, or as the keyword reads now.

removedbooleanRequired

The keyword has since been deleted. Its charges stay on the record; its mentions went with it, so its mention counts read 0.

groupobjectnullableRequired

by=group only; null otherwise.

+Show 3 properties

idstringRequired

Group id, or "none" for keyword-days metered before groups existed whose keyword is gone.

namestringRequired

The group's name as it reads now, or "Deleted group" / "No group".

removedbooleanRequired

The group has since been deleted.

keywordDaysintegernullableRequired

Keyword-days the daily tick charged in this row. Null for by=platform and for days before the first recorded tick (unknown, not zero); before window.keywordDaysFrom a keyword row is a floor.

0 to ∞

keywordCentsintegerRequired

The keyword-days at the keyword rate ($5 a month, 500/30 cents a day), rounded once on the total.

matchedMentionsintegerRequired

Matches recorded in the window, relevant or not.

0 to ∞

billableMentionsintegerRequired

Of the matches billed in the window (every scored match, relevant or not), the ones in this group.

0 to ∞

unclassifiedMentionsintegerRequired

Matches in the window that are never charged: not scored yet, classification failed, or a free review from a new app's look-back. Every other match is charged, on the mentions or comments line.

0 to ∞

mentionCentsintegerRequired

The billed mentions at $0.008 each, rounded once on the total.

billableCommentsintegerRequired

Comments billed in the window (the comments line): comments delivered under your mentions and comments that matched a keyword, each once per workspace.

0 to ∞

commentCentsintegerRequired

The billed comments at $0.008 each, rounded once on the total.

totalCentsintegerRequired

keywordCents plus mentionCents plus commentCents.

totalintegerRequired

Rows in the dimension before limit and offset.

0 to ∞

400Unknown dimension or range, month malformed or in the future, limit out of range

+Show 1 property

errorobjectRequired

The error.

+Show 4 properties

codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 46 enum values

unauthorizedforbiddenread_only_keyvalidation_errornot_foundinvalid_cursorpayload_too_largeidempotency_key_in_useidempotency_key_reusedrate_limitedduplicate_keywordinsufficient_balancekeyword_limit_reachedbilling_not_configuredorder_not_creditedschedule_requiredunknown_channelnot_a_digesthourly_email_unsupportedslack_not_connectedslack_not_configuredtelegram_not_configuredfeed_unreadablefeed_login_requiredfeed_login_expiredfeed_limit_reachedfeed_auth_not_configuredemail_not_configuredinvalid_assigneeclassification_pendinginvalid_memberalready_memberlast_ownerduplicate_segmentfilter_too_complexduplicate_viewduplicate_groupdefault_groupdefault_group_contextgroup_changedinvalid_signaturewebhook_not_configuredinvalid_tokenprotected_userupstream_unavailableinternal_error

messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

401Missing or invalid API key

+Show 1 property

errorobjectRequired

The error.

+Show 4 properties

codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 46 enum values

messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

429More than 30 breakdown reads this minute for the workspace

+Show 1 property

errorobjectRequired

The error.

+Show 4 properties

codestringRequired

Stable machine-readable code; branch on this, never on the message. Codes are additive: a client should treat one it does not know as a generic failure of the same status.

+Show 46 enum values

messagestringRequired

Human-readable detail; may change between releases.

requestIdstringOptional

The id of this request (also the X-Request-Id response header); quote it to support.

retryAfterSecondsintegerOptional

For rate_limited and other retryable errors: how long to wait before retrying (mirrors the Retry-After header).

https://api.mentio.dev/v1/usage/breakdown

const response = await fetch('https://api.mentio.dev/v1/usage/breakdown', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MENTIO_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);

Response

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

View as Markdown Ask ChatGPT about this page Ask Claude about this page OpenAPI specification Get an API key