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": [],
    "mentionType": "Original Post",
    "media": [
      {
        "url": "<string>"
      }
    ],
    "language": "<string>",
    "botRating": "almost_certain",
    "enrichments": {
      "narratives": [
        {
          "id": 123,
          "confidence": 50
        }
      ],
      "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"
      }
    ],
    "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>'

[
  {
    "id": 1234,
    "title": "<string>",
    "text": "<string>",
    "url": "<string>",
    "domain": "<string>",
    "author": "<string>",
    "reach": 1250000,
    "channels": [],
    "mentionType": "Original Post",
    "media": [
      {
        "url": "<string>"
      }
    ],
    "language": "<string>",
    "botRating": "almost_certain",
    "enrichments": {
      "narratives": [
        {
          "id": 123,
          "confidence": 50
        }
      ],
      "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"
      }
    ],
    "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. 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 standard 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

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.

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.

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

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

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

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"
  }
]

publisherGeography

object

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

Narratives

Custom channels

⌘I