Mentions

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

import requests

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

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}/mentions', 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}/mentions",
  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}/mentions"

	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}/mentions")

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

[
  {
    "id": 1234,
    "title": "<string>",
    "text": "<string>",
    "url": "<string>",
    "domain": "<string>",
    "author": "<string>",
    "reach": 1250000,
    "channels": [
      "blogsdiscussions"
    ],
    "mentionType": "Original Post",
    "media": [
      {
        "type": "image",
        "url": "<string>"
      }
    ],
    "language": "<string>",
    "botRating": "almost_certain",
    "enrichments": {
      "sentiment": {
        "polarity": 0,
        "version": 0
      },
      "engagement": {
        "history": [
          {
            "measured_at": "2026-05-12T15:18:26.258957+00:00",
            "views": 1839,
            "retweets": 2,
            "quotes": 0,
            "replies": 1,
            "favorites": 7,
            "bookmarks": 0
          }
        ]
      }
    },
    "smartCategories": [
      {
        "categoryName": "Favorability",
        "classification": "244:c0"
      }
    ],
    "customEnrichments": [
      {
        "enrichmentName": "Disinformation Analysis",
        "value": "Substantiated"
      }
    ],
    "location": {
      "region": {
        "id": 1,
        "name": "Americas"
      },
      "subregion": {
        "id": 3,
        "name": "Northern America"
      },
      "country": {
        "id": 10,
        "name": "United States"
      },
      "state": {
        "id": 6,
        "name": "California"
      },
      "county": null,
      "city": {
        "id": 512,
        "name": "San Francisco"
      },
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "publisherGeography": {
      "sourceCountry": "United States",
      "sourceRegion": "Americas",
      "sourceSubRegion": "Northern America"
    },
    "created": "2023-11-07T05:31:56Z",
    "processed": "2023-11-07T05:31:56Z",
    "published": "2023-11-07T05:31:56Z"
  }
]

Workspaces

Mentions

A mention is the fundamental data unit in PeakMetrics—a piece of content written by an author, promoted by a publisher, and released on a domain as part of a channel. Typically, this is a news article or social media post.

All standard mention filters from GET /workspaces/{workspaceId}/available-filters can be applied to narrow the results. Use that endpoint to discover the friendly names associated with each the response parameters of this endpoint, which are derived from each filter’s key.

Randomized sampling — Pass an optional randomization_key query parameter to receive a randomized sample of up to 500 mentions instead of the default sorted results. The randomized pool is cached for 5 minutes, so repeating the same key with different offset values lets you paginate through a stable, shuffled set. When randomization_key is omitted the endpoint behaves as before, returning mentions in the requested sort order.

GET

workspaces

{workspaceId}

mentions

Mentions

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

import requests

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

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}/mentions', 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}/mentions",
  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}/mentions"

	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}/mentions")

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

[
  {
    "id": 1234,
    "title": "<string>",
    "text": "<string>",
    "url": "<string>",
    "domain": "<string>",
    "author": "<string>",
    "reach": 1250000,
    "channels": [
      "blogsdiscussions"
    ],
    "mentionType": "Original Post",
    "media": [
      {
        "type": "image",
        "url": "<string>"
      }
    ],
    "language": "<string>",
    "botRating": "almost_certain",
    "enrichments": {
      "sentiment": {
        "polarity": 0,
        "version": 0
      },
      "engagement": {
        "history": [
          {
            "measured_at": "2026-05-12T15:18:26.258957+00:00",
            "views": 1839,
            "retweets": 2,
            "quotes": 0,
            "replies": 1,
            "favorites": 7,
            "bookmarks": 0
          }
        ]
      }
    },
    "smartCategories": [
      {
        "categoryName": "Favorability",
        "classification": "244:c0"
      }
    ],
    "customEnrichments": [
      {
        "enrichmentName": "Disinformation Analysis",
        "value": "Substantiated"
      }
    ],
    "location": {
      "region": {
        "id": 1,
        "name": "Americas"
      },
      "subregion": {
        "id": 3,
        "name": "Northern America"
      },
      "country": {
        "id": 10,
        "name": "United States"
      },
      "state": {
        "id": 6,
        "name": "California"
      },
      "county": null,
      "city": {
        "id": 512,
        "name": "San Francisco"
      },
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "publisherGeography": {
      "sourceCountry": "United States",
      "sourceRegion": "Americas",
      "sourceSubRegion": "Northern America"
    },
    "created": "2023-11-07T05:31:56Z",
    "processed": "2023-11-07T05:31:56Z",
    "published": "2023-11-07T05:31:56Z"
  }
]

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

randomization_key

string

When provided, the endpoint returns a randomized sample of up to 500 mentions instead of sorted results; sort and order are ignored. The value seeds the random ordering and acts as a cache key (TTL 5 minutes). Reuse the same value across paginated requests for stable results. When omitted, the endpoint returns mentions in the requested (default published desc) sort order.

limit

integer

The maximum number of mentions to return, default 10. To get more mentions, use in combination with the offset parameter to paginate.

Required range: 1 <= x <= 50

offset

integer

The number of mentions to skip before returning, default 0. Use in combination with the limit parameter to paginate.

Required range: x >= 0

sort

The field to sort the mentions by, default published.

created and published sort by the mention's dates. custom_enrichment_id:{enrichment_id} sorts by the value of one of your team's integer custom enrichments (e.g. custom_enrichment_id:1681); mentions that have no value for that enrichment are returned after every mention that has one, whichever order is requested. Naming a categorical enrichment, or an enrichment your team does not have, is a 400. Find your enrichment ids with GET /customEnrichments.

Ignored when randomization_key is set.

Available options:

created,

published

order

enum<string>

The order to sort the mentions by, default desc. Ignored when randomization_key is set.

Available options:

asc,

desc

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.

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 array of mention objects

integer

The unique identifier for the mention.

Example:

1234

title

string

The title for the mention, if available.

text

string

The text for the mention, if available.

url

string

The original URL to the mention.

domain

string

The domain of the mention URL—a distinct subset of the internet with URL addresses sharing a common suffix or under the control of a particular organization or individual.

Domain Types:

News organizations publishing content through their website
Social networks and messaging platforms
Blogs and independent publishers
Video and media platforms

Note: Common sub-domains such as www are normalized and removed.

Examples: nytimes.com, twitter.com, telegram.org, reddit.com

author

string

The author of the mention—an individual who writes a piece of digital content, indicated by the byline or social account attached to the content.

Author Types:

Journalists and reporters
Social media accounts and influencers
Blog writers and content creators
Public figures and verified accounts

Understanding author attribution helps identify the voices driving narratives and assess source credibility.

reach

integer | null

The reach metric for this mention. For news publishers, this represents the UVM (Unique Visitor Monthly) count. For social media accounts, this represents the number of followers. Null when reach data is not available.

Example:

1250000

channels

enum<string>[]

A Channel represents a specific type of platform where content is released and consumed. PeakMetrics monitors millions of sources across traditional and emerging channels to provide comprehensive narrative intelligence.

Available Channels:

News: Traditional news outlets and online publications
Social Media: Twitter, Facebook, Instagram, Threads, Bluesky
Video Platforms: YouTube, TikTok
Discussion Forums: Reddit, Reddit Comments, Telegram
International Platforms: VK (Russian), Weibo (Chinese)
Blogs & Discussions: General blogs and discussion platforms

Multi-channel monitoring helps identify how narratives spread across different platforms and audiences, enabling comprehensive media intelligence analysis.

Available options:

blogsdiscussions,

bluesky,

facebook,

instagram,

news,

reddit,

redditComment,

telegram,

threads,

tiktok,

twitter,

vk,

weibo,

youtube

mentionType

enum<string> | null

The mention type, represented as the mention type's key.value.

Available options:

social_media.original_posts,

social_media.reposts,

social_media.comments,

social_media.quoting_posts,

news.news,

podcasts.podcasts

Example:

"Original Post"

media

object[]

Show child attributes

language

string

The language of the mention, represented as a two-letter ISO 639-1 code.

Common Language Codes:

en - English
es - Spanish
fr - French
de - German
zh - Chinese
ru - Russian

Note: Language is detected automatically using machine learning and may not be 100% accurate.

botRating

enum<string> | null

The bot detection confidence level for this mention, represented the rating's value. Only applicable to social media mentions. Null for non-social media mentions or when bot detection is not available.

Available options:

none,

further_investigation,

very_unlikely,

unlikely,

potential,

likely,

very_likely,

almost_certain

Example:

"almost_certain"

enrichments

object

The enrichments of the mention.

Show child attributes

smartCategories

object[]

The Smart Category classifications assigned to this mention. Smart Categories are custom AI-powered classifiers configured per workspace (e.g., sentiment models, topic classifiers, violent rhetoric detection). Each classification includes the category name and classification label as returned by GET /workspaces/{workspaceId}/available-filters.

Show child attributes

Example:

[
  {
    "categoryName": "Favorability",
    "classification": "244:c0"
  }
]

customEnrichments

object[]

The custom enrichment values written for this mention. Custom enrichments are structured fields provisioned for your team that attach external context to mentions, as listed for this workspace by GET /workspaces/{workspaceId}/available-filters under custom_enrichments.

Returns an empty array if no custom enrichment values have been written for this mention, or if no custom enrichments are available for this workspace.

Show child attributes

Example:

[
  {
    "enrichmentName": "Disinformation Analysis",
    "value": "Substantiated"
  }
]

location

object

The mention's normalized location, drawn from PeakMetrics' six-level location taxonomy. This replaces publisherGeography and, unlike it, resolves on mentions across every channel rather than news only.

All six level keys are always present: a level the mention did not resolve to is null rather than omitted. state and county are United States only, so non-US mentions resolve to a country and, where the source is specific enough, a city.

Each level's id can be passed straight back into the matching locations.<level> filter on this endpoint, /analytics/timeline, and /analytics/distribution. Look names and ids up with GET /locations.

Location resolution is best effort and coverage varies by channel — strong for news, partial for social. Location is available on mentions published on or after July 1, 2026; mentions published before that date carry no normalized location.

Show child attributes

Example:

{
  "region": { "id": 1, "name": "Americas" },
  "subregion": { "id": 3, "name": "Northern America" },
  "country": { "id": 10, "name": "United States" },
  "state": { "id": 6, "name": "California" },
  "county": null,
  "city": { "id": 512, "name": "San Francisco" },
  "latitude": 37.7749,
  "longitude": -122.4194
}

publisherGeography

object

deprecated

Deprecated — removed on December 1, 2026. Use the location object instead, which resolves on mentions across every channel rather than news only and returns ids you can feed straight back into the locations.<level> filters.

(News only) The location of the news publisher, as provided by LexisNexis (not supported for all news sites).

Show child attributes

created

string<date-time>

The date and time the mention was created.

processed

string<date-time>

The date and time the mention was last updated.

published

string<date-time>

The date and time the mention was published by its source.

⌘I