Skip to main content
GET
Volume over time (day / week / month, optional split)

Authorizations

Authorization
string
header
required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>. Keys carry a scope — read, write (implies read) or admin (implies write) — chosen when the key is minted. Each operation's security requirement (and its x-required-scope extension) names the minimum scope it needs; request the least-privileged key that covers the operations you call.

Query Parameters

keywordIds

Numeric ids of the monitored keywords to scope to (from list_keywords). Omit for every keyword. A mention that matched several keywords counts once per keyword in per-keyword breakdowns and once in totals.

Required range: 0 < x <= 9007199254740991
startDate
string

Inclusive first day of the window as YYYY-MM-DD (UTC) — NEVER an ISO timestamp with T/Z. Omit for the default: the last 30 days ending today.

Pattern: ^\d{4}-\d{2}-\d{2}$
endDate
string

Inclusive last day of the window as YYYY-MM-DD (UTC). Omit for today. Must be on or after startDate; the window may span at most 365 days.

Pattern: ^\d{4}-\d{2}-\d{2}$
includeAll

Count every collected mention, including the ones the AI scored Low relevance or has not scored yet. Default false: only relevant mentions (High + Medium) count — the same set the mentions feed shows by default.

granularity
enum<string>
default:day

Bucket size: day, week (weeks start on Sunday), or month. Default day. Pick the one that gives roughly 5–30 buckets for the window.

Available options:
day,
week,
month
splitBy
enum<string>

Optional second dimension: one row per bucket AND keyword / source / sentiment (the series field). Omit for one total per bucket.

Available options:
keyword,
source,
sentiment

Response

200 response

window
object
required
granularity
enum<string>
required
Available options:
day,
week,
month
includeAll
boolean
required
total
integer
required

Distinct mentions in the window (never double-counts a mention that matched several keywords, so a keyword split's rows can sum to more than this).

Required range: -9007199254740991 <= x <= 9007199254740991
data
object[]
required

Sorted by bucket asc (then count desc within a bucket). Empty buckets omitted.

splitBy
enum<string>
Available options:
keyword,
source,
sentiment