Skip to main content
POST
Explore query distribution

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"

group_by
enum<string>
required

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: the top 50 domains by count.
  • 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 the top 100 languages per channel; mentions with no detected language are not listed.

Required on this endpoint. A missing group_by, or any other value, is rejected with a 400.

Available options:
channels,
domains,
languages
Example:

"channels"

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:

Response

A JSON object containing the mention count distribution.

totalCount
number
required

Total number of matching mentions. 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

groups
object[]
required

The breakdown by the group_by dimension, ordered by count, highest first.

With group_by: "channels", each entry's key is a channel you requested, with one reddit entry for Reddit posts and comments.

With group_by: "domains", this contains the top 50 domains by count.

With group_by: "languages" and twitter in channels, this contains exactly two entries, en and non_en. Without twitter, it contains the full breakdown up to the top 100 languages per channel; mentions with no detected language are not listed. English variants (for example, en-us and en-gb) are always reported as en.

Domains and languages beyond these caps are not listed, and without twitter neither are mentions with no detected language (with twitter, they are counted in non_en). Each percentage is also rounded to one decimal place, so the percentage values need not add up to 100.

groupBy
enum<string>

The dimension used for this distribution, as sent in group_by.

Available options:
channels,
domains,
languages
Example:

"channels"