Skip to main content
POST
Explore query volume over time

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The JSON request body shared by POST /explore/analytics/timeline and POST /explore/analytics/distribution. Parameters are sent in the body rather than the query string because query can contain quotes, parentheses, and boolean operators that are awkward to URL-encode, and channels is an array.

query
string
required

The search query to execute. Supports a reduced boolean syntax: AND, OR, NOT, parenthetical grouping, and the title:, author:, and domain: field scopes. An unparseable query (for example, unbalanced parentheses or an unsupported field-scope operator) is rejected with a 400.

A query can be up to 2,000 characters long and contain up to 100 terms, where a quoted phrase counts as one term. A query over either limit is rejected with a 400.

domain: terms don't apply to Twitter. When channels includes twitter, Twitter counts ignore any domain: terms in the query, and a query with nothing left for Twitter without them (for example, a query made only of domain: terms) is rejected with a 400.

Example:

"(\"Delta Airlines\" OR title:Delta) AND delay NOT domain:example.com"

channels
enum<string>[]
required

The channels to search. Access to each channel is governed by your account's channel entitlements, consistent with the rest of the PeakMetrics platform. Requesting a channel your account is not entitled to is rejected with a 403.

reddit covers the Reddit posts and comments your account is entitled to: posts, comments, or both. It is rejected with a 403 only when your account is entitled to neither.

Minimum array length: 1
Available options:
news,
reddit,
twitter,
vk,
weibo
Example:
since
required

The minimum published date of the mentions to include. Required, along with to. Send an ISO 8601 date-time or epoch milliseconds; any other value is rejected with a 400. Dates are aligned to UTC day boundaries: the range starts at 00:00:00 UTC on the day since falls on.

The range can reach back 12 months from the start of the current UTC day. A since up to one day earlier than that is clamped to the start of the 12-month range; a since further back is rejected with a 400, and so is a since on a later UTC day than to or than today.

Example:

"2026-06-14T00:00:00Z"

to
required

The maximum published date of the mentions to include. Required, along with since. Send an ISO 8601 date-time or epoch milliseconds; any other value is rejected with a 400. Dates are aligned to UTC day boundaries: the range includes the whole UTC day to falls on. A to in the future is clamped to today, so the range ends with the current UTC day.

Example:

"2026-09-14T23:59:59Z"

domains
string[]

Filter to mentions published on the provided domains. Multiple values are combined with OR logic. When omitted, all domains are included. Up to 50 values are accepted; more are rejected with a 400.

When channels includes twitter and you set domains, Twitter is counted only if domains includes twitter.com. Otherwise Twitter contributes 0 to every count, and the request still succeeds. x.com is not an alias for twitter.com: list twitter.com to keep Twitter in the results.

Example:
languages
string[]

Filter to mentions in the provided languages, specified as two-letter ISO 639-1 codes. Codes are case-insensitive, so EN is the same as en. Use non_en to match every language other than English; en also matches regional English variants such as en-us and en-gb. Multiple values are combined with OR logic. When omitted, all languages are included. Up to 50 values are accepted; more are rejected with a 400.

When channels includes twitter, languages may only contain en, non_en, or both. Any other value (for example, a specific non-English language code) is rejected with a 400.

Example:
group_by
enum<string>

Breakdown dimension:

  • channels — Counts by channel. Each group's key is a channel id from your channels list; Reddit posts and comments are counted together under reddit.
  • domains — Counts by domain: each day's top domains, up to 30 per channel and at most 50 in all.
  • languages — Counts by language. English variants (for example, en-us and en-gb) are reported as en. When channels includes twitter, the breakdown contains exactly two groups, en and non_en. Otherwise it contains the full breakdown up to each day's top 30 languages per channel; mentions with no detected language are not listed.

When omitted, each bucket's groups is returned as an empty array. Any other value is rejected with a 400.

Available options:
channels,
domains,
languages
Example:

"channels"

Response

A JSON object containing time-bucketed mention volume.

totalCount
number
required

Total number of matching mentions across all time buckets. Data for some channels may be estimated from a large-scale firehose sample: Reddit comments, VK, and Weibo are sampled (20%, 20%, and 10% of the firehose, respectively) and their counts are extrapolated from the sample, while News, Reddit posts, and Twitter are counted in full.

Required range: x >= 0
Example:

13100

buckets
object[]
required

Mention volume aggregated into daily buckets, oldest first: one bucket for every UTC calendar day in the requested date range. A day with no matching mentions is still returned, with a count of 0.