Mention count distribution

Authorizations

Authorization

string

header

required

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

Path Parameters

workspaceId

integer

required

The unique identifier for the workspace.

Required range: x >= 1

Query Parameters

since

string<date-time>

required

The minimum published date of the mentions to return.

string<date-time>

required

The maximum published date of the mentions to return.

group_by

string

required

The dimension to distribute mention counts by. The value must be a valid filter key as returned by GET /workspaces/{workspaceId}/available-filters, or one of the following built-in dimensions:

channels — Mention counts by channel
authors — Top authors by mention count
domains — Top domains by mention count
languages — Mention counts by detected language
bot_ratings — Mention counts by bot detection confidence
locations.region — Mention counts by region
locations.subregion — Mention counts by subregion
locations.country — Mention counts by country
locations.state — Mention counts by state
locations.county — Mention counts by county
locations.city — Mention counts by city
publisher_geography.source_country — Mention counts by publisher country (deprecated — removed December 1, 2026, use locations.country)
publisher_geography.source_region — Mention counts by publisher region (deprecated — removed December 1, 2026, use locations.region)
publisher_geography.source_sub_region — Mention counts by publisher subregion (deprecated — removed December 1, 2026, use locations.subregion)

For Smart Categories and Custom Enrichments, use the format {model_key}:{enrichment_id}, where model_key is either smart_category_enrichment_id or custom_enrichment_id and enrichment_id is the model's ID (e.g., smart_category_enrichment_id:244 or custom_enrichment_id:1681). Available IDs are returned by GET /workspaces/{workspaceId}/available-filters.

The six locations.* dimensions break counts down by PeakMetrics' location taxonomy. Each group's key is the location id as a string and name is its display name, so a group feeds straight back into the matching locations.<level> filter. group_by takes a single value, so you can break down by only one level at a time. Grouping by locations.county or locations.city returns only the locations that mentions actually resolved to that depth.

metric

string

default:mentions

What each bucket or group measures. One of:

mentions (default) — the number of mentions. Existing behavior, unchanged.
reach — the sum of the reach of the mentions.
custom_enrichment_sum:{enrichment_id} — the sum of an integer custom enrichment's values across the mentions, where enrichment_id is the enrichment_id returned by GET /customEnrichments (e.g. custom_enrichment_sum:1681). Only integer enrichments provisioned for your team are accepted; a categorical enrichment or an id your team does not hold is a 400.

The response shape does not change with the metric: count and totalCount report the number of mentions by default, and the summed value of the chosen metric when one is set. Mentions that carry no value for the chosen field contribute nothing to a sum. All filters and group_by apply alongside any metric.

channels

enum<string>[]

Filter to mentions that are part of the provided channel.

Available options:

blogsdiscussions,

bluesky,

facebook,

instagram,

news,

reddit,

redditComment,

telegram,

threads,

tiktok,

twitter,

vk,

weibo,

youtube

filter_expression

string

A keyword search string applied against mention content. Supports Boolean operators (AND, OR, NOT) and quoted phrases for exact matching. Field-scoped expressions are also supported (e.g., title:word or text:phrase).

This filter is applied in addition to the workspace query and any other filters. Use this for ad-hoc keyword narrowing without modifying the workspace configuration.

domains

string[]

Filter to mentions published on the provided domains. Multiple values are combined with OR logic.

authors

string[]

Filter to mentions attributed to the provided authors. Multiple values are combined with OR logic.

languages

string[]

Filter to mentions in the provided languages, specified as two-letter ISO 639-1 codes. Multiple values are combined with OR logic.

bot_ratings

enum<string>[]

Filter by bot detection confidence level. Bot detection analyzes social media accounts to identify automated or coordinated inauthentic behavior. Multiple values are combined with OR logic.

Available options:

none,

further_investigation,

very_unlikely,

unlikely,

potential,

likely,

very_likely,

almost_certain

smart_categories

string[]

Filter by Smart Category classification results. Smart Categories are custom AI-powered classifiers configured per workspace (e.g., sentiment models, topic classifiers, violent rhetoric detection).

Each value is a composite string in the format {enrichmentId}:{categoryKey}, where enrichmentId identifies the Smart Category model and categoryKey identifies the classification label (e.g., c0, c1, c2).

Available enrichment IDs and their category key mappings can be discovered via GET /workspaces/{workspaceId}/available-filters. Multiple values are combined with OR logic.

custom_enrichments

string[]

Filter by custom enrichment values. Custom enrichments are structured fields provisioned for your team that attach external context to mentions.

Each value is a composite string in the format {enrichment_id}:{value}, where enrichment_id identifies the custom enrichment and value is the category value to match (e.g., 1681:Substantiated).

Available custom enrichments and their recorded values for this workspace can be discovered via GET /workspaces/{workspaceId}/available-filters under custom_enrichments. Multiple values are combined with OR logic.

Filter by social media post type. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.social_media.options. Multiple values from the same sub-filter are combined with OR logic.

Available options:

original_posts,

reposts,

comments,

quoting_posts

mention_type.news

enum<string>[]

Filter to news mention type. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.news.options. Multiple values are combined with OR logic.

Available options:

news

mention_type.podcasts

enum<string>[]

Filter to podcast mention types. Use the values returned by GET /workspaces/{workspaceId}/available-filters under mention_type.podcasts.options. Multiple values are combined with OR logic.

Available options:

podcasts

locations.region

integer[]

Filter to mentions that resolved to the provided regions, identified by the numeric id returned by GET /locations?level=region. Location ids are unique only within a level, so these must be region ids.

Selecting a region also matches mentions that resolved to anything beneath it — its subregions, countries, states, counties, and cities — so there is no need to enumerate children. Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

locations.subregion

integer[]

Filter to mentions that resolved to the provided subregions, identified by the numeric id returned by GET /locations?level=subregion. Location ids are unique only within a level, so these must be subregion ids.

Selecting a subregion also matches mentions that resolved to anything beneath it — its countries, states, counties, and cities — so there is no need to enumerate children. Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

locations.country

integer[]

Filter to mentions that resolved to the provided countries, identified by the numeric id returned by GET /locations?level=country. Location ids are unique only within a level, so these must be country ids.

Selecting a country also matches mentions that resolved to anything beneath it — its states, counties, and cities — so there is no need to enumerate children. Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

locations.state

integer[]

Filter to mentions that resolved to the provided states, identified by the numeric id returned by GET /locations?level=state. States are United States only. Location ids are unique only within a level, so these must be state ids.

Selecting a state also matches mentions that resolved to anything beneath it — its counties and cities — so there is no need to enumerate children. Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

locations.county

integer[]

Filter to mentions that resolved to the provided counties, identified by the numeric id returned by GET /locations?level=county. Counties are United States only. Location ids are unique only within a level, so these must be county ids.

Selecting a county also matches mentions that resolved to any of its cities, so there is no need to enumerate children. Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

locations.city

integer[]

Filter to mentions that resolved to the provided cities, identified by the numeric id returned by GET /locations?level=city. City is the finest level of the taxonomy, so it has no descendants. Location ids are unique only within a level, so these must be city ids.

Multiple values are combined with OR logic, and all six locations.* parameters are OR'd together as a single group, which is then combined with your other filters using AND logic.

publisher_geography.source_country

string[]

Deprecated — removed on December 1, 2026. Use the locations.country filter instead, which resolves on mentions across every channel rather than news only. Look ids up with GET /locations?level=country.

Filter by the publisher's country of origin. Primarily applicable to news mentions. Country names should match the values returned by GET /workspaces/{workspaceId}/available-filters. Multiple values are combined with OR logic.

publisher_geography.source_region

enum<string>[]

Deprecated — removed on December 1, 2026. Use the locations.region filter instead, which resolves on mentions across every channel rather than news only. Look ids up with GET /locations?level=region.

Filter by the publisher's geographic region. Primarily applicable to news mentions. Multiple values are combined with OR logic.

Available options:

Africa,

Americas,

Asia,

Europe,

Oceania

publisher_geography.source_sub_region

enum<string>[]

Deprecated — removed on December 1, 2026. Use the locations.subregion filter instead, which resolves on mentions across every channel rather than news only. Look ids up with GET /locations?level=subregion.

Filter by the publisher's geographic subregion. Primarily applicable to news mentions. Multiple values are combined with OR logic.

Available options:

Australia and New Zealand,

Caribbean,

Central America,

Central Asia,

Eastern Africa,

Eastern Asia,

Eastern Europe,

Melanesia,

Micronesia,

Middle Africa,

Northern Africa,

Northern America,

Northern Europe,

Polynesia,

South America,

South-Eastern Asia,

Southern Africa,

Southern Asia,

Southern Europe,

Western Africa,

Western Asia,

Western Europe

Response

A JSON object containing the mention count distribution.

groupBy

string

The dimension used for this distribution.

Example:

"channels"

totalCount

number

Total across the matching mentions: the number of mentions, or with metric set, the summed value of that metric. This may be larger than the sum of group counts if the dimension has many distinct values.

Required range: x >= 0

Example:

125000

groups

object[]

One entry per value within the specified dimension, sorted by count descending.

Show child attributes