Skip to main content
GET
/
workspaces
/
{workspaceId}
/
analytics
/
timeline
Mention volume over time
curl --request GET \
  --url https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline \
  --header 'Authorization: Bearer <token>'
{
  "totalCount": 125000,
  "buckets": [
    {
      "date": "2025-01-15T00:00:00Z",
      "count": 1,
      "groups": [
        {
          "key": "<string>",
          "count": 1
        }
      ]
    }
  ]
}

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.

​
to
string<date-time>
required

The maximum published date of the mentions to return.

​
group_by
string

Adds a secondary breakdown within each time bucket by the specified dimension. The value must be a valid filter key as returned by GET /workspaces/{workspaceId}/available-filters, or one of the following built-in dimensions:

  • bot_ratings — Mention counts by bot detection confidence
  • mention_type.social_media — Mention counts by social media post type
  • publisher_geography.source_country — Mention counts by publisher country
  • publisher_geography.source_region — Mention counts by publisher region
  • publisher_geography.source_sub_region — Mention counts by publisher 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.

When omitted, each bucket contains only the total mention count. When provided, each bucket includes a groups array with counts broken down by the dimension's option values.

​
narratives.id
number[]

Filter the returned results to those that are part of the provided narrative IDs.

​
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.

​
mention_type.social_media
enum<string>[]

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
​
publisher_geography.source_country
string[]

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>[]

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>[]

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 time-bucketed mention volume.

​
totalCount
integer

Total count of all mentions matching the filters across all time buckets.

Required range: x >= 0
Example:

125000

​
buckets
object[]

Mention volume aggregated into daily buckets over the requested date range.