Skip to main content
GET
/
workspaces
/
{workspaceId}
/
mentions
Mentions
curl --request GET \
  --url https://api.peakmetrics.com/workspaces/{workspaceId}/mentions \
  --header 'Authorization: Bearer <token>'
[
  {
    "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": {
      "narratives": [
        {
          "id": 123,
          "confidence": 50
        }
      ],
      "sentiment": {
        "polarity": 0,
        "version": 1
      }
    },
    "smartCategories": [
      {
        "categoryName": "Favorability",
        "classification": "244:c0"
      }
    ],
    "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

​
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
enum<string>

The field to sort the mentions by descending, default published.

Available options:
created,
published,
confidence
​
order
enum<string>

The order to sort the mentions by, default desc.

Available options:
asc,
desc
​
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.

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

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

​
id
integer

The unique identifier for the narrative.

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

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

Example:
[
  {
    "categoryName": "Favorability",
    "classification": "244:c0"
  }
]
​
publisherGeography
object

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

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