Mention volume over time

curl --request GET \
  --url https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "totalCount": 125000,
  "buckets": [
    {
      "date": "2025-01-15T00:00:00Z",
      "count": 1,
      "groups": [
        {
          "key": "<string>",
          "name": "San Francisco",
          "count": 1
        }
      ]
    }
  ]
}

Workspaces

Mention volume over time

Returns mention volume aggregated into time buckets over the requested date range. Use the optional group_by parameter to add a secondary breakdown within each bucket by any filterable dimension (e.g., channel, language, bot rating, smart category, etc.), and the optional metric parameter to measure reach or an integer custom enrichment instead of mention counts.

The bucket size follows the length of the requested range: hourly up to 10 days, daily up to 100 days, weekly up to about six months, monthly beyond that. Each bucket’s date is its start, in UTC.

All standard mention filters can be applied to narrow the results.

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>'

import requests

url = "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.peakmetrics.com/workspaces/{workspaceId}/analytics/timeline")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "totalCount": 125000,
  "buckets": [
    {
      "date": "2025-01-15T00:00:00Z",
      "count": 1,
      "groups": [
        {
          "key": "<string>",
          "name": "San Francisco",
          "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.

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:

channels — Mention counts by channel
bot_ratings — Mention counts by bot detection confidence
mention_type.social_media — Mention counts by social media post type
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. For these six dimensions only, each entry in a bucket's groups array carries an extra name field holding the location's display name, while key holds the location id as a string. Location names are not unique across levels — Georgia is both a US state and a country — and it is the id that round-trips back into the locations.<level> filter, so the name is returned separately. Every other dimension is unchanged and still carries its label in key.

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.

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.

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

totalCount

number

Total across all time buckets: the number of mentions matching the filters, or with metric set, the summed value of that metric (reach, or the integer enrichment's values).

Required range: x >= 0

Example:

125000

buckets

object[]

Mention volume aggregated into time buckets over the requested date range (hourly, daily, weekly or monthly depending on the range; see the endpoint description).

Show child attributes

⌘I