> ## Documentation Index > Fetch the complete documentation index at: https://docs.peakmetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api/api_docs.yaml get /workspaces/{workspaceId}/mentions openapi: 3.1.0 info: title: PeakMetrics API description: > The PeakMetrics API provides programmatic access to narrative intelligence data. Access millions of mentions across news, social media, and online platforms, enriched with custom AI-powered smart categories and over 50 metadata properties. The API enables you to identify, analyze, and act on emerging narratives in real-time. version: 2.0.0 servers: - url: https://api.peakmetrics.com description: Main (production) server security: - BearerAuth: [] tags: - name: Authorization - name: Workspaces - name: Folders - name: Channels - name: Custom Channels - name: Custom Enrichments description: > Custom enrichments let you push external context about mentions into PeakMetrics, attached to individual mentions and used alongside all other mention metadata across the platform. Once written, enrichment values feed into narrative analysis, workspace summaries, and notifications, and are available through the customer API and the MCP server. Your team manages its own custom enrichments through the API: create one with `POST /customEnrichments`, list them with `GET /customEnrichments`, rename one or replace its option list with `PUT /customEnrichments/{enrichmentId}`, retire one with `DELETE /customEnrichments/{enrichmentId}`, and push values for individual mentions with `PUT /mentions/customEnrichments`. paths: /workspaces/{workspaceId}/mentions: get: tags: - Workspaces summary: Mentions description: > 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. parameters: - $ref: '#/components/parameters/WorkspaceId' - in: query name: randomization_key required: false schema: type: string description: | 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. example: abc123-session-key - in: query name: limit required: false schema: type: integer maximum: 50 minimum: 1 description: | The maximum number of mentions to return, default 10. To get more mentions, use in combination with the offset parameter to paginate. - in: query name: offset required: false schema: type: integer minimum: 0 description: >- The number of mentions to skip before returning, default 0. Use in combination with the limit parameter to paginate. - in: query name: sort required: false schema: type: string enum: - created - published - confidence description: The field to sort the mentions by descending, default published. - in: query name: order required: false schema: type: string enum: - asc - desc description: The order to sort the mentions by, default desc. - $ref: '#/components/parameters/Since' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/NarrativeIds' - $ref: '#/components/parameters/Channels' - $ref: '#/components/parameters/FilterExpression' - $ref: '#/components/parameters/Domains' - $ref: '#/components/parameters/Authors' - $ref: '#/components/parameters/Languages' - $ref: '#/components/parameters/BotRatings' - $ref: '#/components/parameters/SmartCategories' - $ref: '#/components/parameters/CustomEnrichments' - $ref: '#/components/parameters/MentionTypeSocialMedia' - $ref: '#/components/parameters/MentionTypeNews' - $ref: '#/components/parameters/MentionTypePodcasts' - $ref: '#/components/parameters/PublisherGeographySourceCountry' - $ref: '#/components/parameters/PublisherGeographySourceRegion' - $ref: '#/components/parameters/PublisherGeographySourceSubRegion' responses: '200': description: A JSON array of mention objects content: application/json: schema: type: array items: type: object properties: id: type: integer description: The unique identifier for the narrative. example: 1234 title: type: string description: The title for the mention, if available. text: type: string description: The text for the mention, if available. url: type: string description: The original URL to the mention. domain: type: string description: > 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: type: string description: > 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: type: - integer - 'null' description: > 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: type: array items: type: string enum: - blogsdiscussions - bluesky - facebook - instagram - news - reddit - redditComment - telegram - threads - tiktok - twitter - vk - weibo - youtube description: > 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. mentionType: type: - string - 'null' description: > The mention type, represented as the mention type's `key.value`. enum: - social_media.original_posts - social_media.reposts - social_media.comments - social_media.quoting_posts - news.news - podcasts.podcasts example: Original Post media: type: array items: type: object properties: type: type: string enum: - image - video url: type: string description: The URL to the media. language: type: string description: > 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: type: - string - 'null' description: > 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. enum: - none - further_investigation - very_unlikely - unlikely - potential - likely - very_likely - almost_certain example: almost_certain enrichments: type: object description: The enrichments of the mention. properties: narratives: description: > The narrative(s) that the mention has been assigned to.
Note that this field is only populated if specific narratives have been requested in the "narratives.id" parameter. type: array items: type: object properties: id: type: integer description: The unique identifier for the narrative. confidence: type: number minimum: 0 maximum: 100 description: >- A score from 0 - 100 denoting the likelihood that this mention belongs the given narrative. sentiment: type: object deprecated: true properties: polarity: type: number minimum: 0 maximum: 0 deprecated: true description: > **Deprecated — always returns `0`** Contact support@peakmetrics.com to set up a custom favorability smart category as an upgraded replacement. version: type: number enum: - 0 deprecated: true description: | **Deprecated — always returns `0`** engagement: type: object description: > Live engagement tracking data for Twitter / X mentions. The `history` array is populated only for Tweets that have been explicitly opted into engagement tracking by a user. For untracked mentions — including mentions on channels that can't be tracked, such as non-Twitter mentions — `history` is returned as an empty array. See [Tracking Tweet Engagement](/help/enrichments-and-integrations/tracking-tweet-engagement) for details on how tracking is enabled and the refresh schedule. properties: history: type: array description: > Timestamped snapshots of engagement metrics captured on a backoff schedule during the first week after the Tweet's published date. Returns an empty array if the mention is not being tracked. items: type: object properties: measured_at: type: string format: date-time description: >- ISO 8601 timestamp for when this snapshot was captured. example: '2026-05-12T15:18:26.258957+00:00' views: type: integer description: >- Number of impressions on the Tweet at the time of capture. example: 1839 retweets: type: integer description: Number of reposts at the time of capture. example: 2 quotes: type: integer description: >- Number of quote-Tweets at the time of capture. example: 0 replies: type: integer description: Number of replies at the time of capture. example: 1 favorites: type: integer description: Number of likes at the time of capture. example: 7 bookmarks: type: integer description: >- Number of times the Tweet has been bookmarked at the time of capture. example: 0 smartCategories: type: array description: > 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`. items: type: object properties: categoryName: type: string description: | The name associated with the smart category model. example: Favorability classification: type: string description: > The value associated with the categorization applied to the mention. example: 244:c0 example: - categoryName: Favorability classification: 244:c0 customEnrichments: type: array description: > 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. items: type: object properties: enrichmentName: type: string description: The name of the custom enrichment. example: Disinformation Analysis value: type: string description: >- The value written for this custom enrichment on this mention. example: Substantiated example: - enrichmentName: Disinformation Analysis value: Substantiated publisherGeography: type: object description: >- (News only) The location of the news publisher, as provided by LexisNexis (not supported for all news sites). properties: sourceCountry: description: | The name of the publisher's country. type: - string - 'null' example: United States sourceRegion: description: | The name of the publisher's region. type: - string - 'null' enum: - Africa - Americas - Asia - Europe - Oceania example: Americas sourceSubRegion: description: | The name of the publisher's subregion. type: - string - 'null' enum: - 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 example: Northern America created: type: string format: date-time description: The date and time the mention was created. processed: type: string format: date-time description: The date and time the mention was last updated. published: type: string format: date-time description: >- The date and time the mention was published by its source. '400': description: Invalid parameters '404': description: No mentions found for the provided workspace ID. components: parameters: WorkspaceId: name: workspaceId in: path required: true schema: type: integer minimum: 1 description: The unique identifier for the workspace. Since: name: since in: query required: true schema: type: string format: date-time description: The minimum published date of the mentions to return. example: '2024-01-01T00:00:00Z' To: name: to in: query required: true schema: type: string format: date-time description: The maximum published date of the mentions to return. example: '2024-01-01T23:59:59Z' NarrativeIds: name: narratives.id in: query required: false schema: type: array items: type: number description: >- Filter the returned results to those that are part of the provided narrative IDs. example: '[1234, 5678]' Channels: name: channels in: query required: false schema: type: array items: type: string enum: - blogsdiscussions - bluesky - facebook - instagram - news - reddit - redditComment - telegram - threads - tiktok - twitter - vk - weibo - youtube description: Filter to mentions that are part of the provided channel. example: '[''twitter'', ''news'']' FilterExpression: name: filter_expression in: query required: false schema: type: string description: > 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. example: (title:word OR text:word2) AND (title:word4 OR text:word3) Domains: name: domains in: query required: false schema: type: array items: type: string description: | Filter to mentions published on the provided domains. Multiple values are combined with OR logic. example: '[''nytimes.com'', ''reuters.com'']' Authors: name: authors in: query required: false schema: type: array items: type: string description: | Filter to mentions attributed to the provided authors. Multiple values are combined with OR logic. example: '[''@exampleuser'', ''Jane Doe'']' Languages: name: languages in: query required: false schema: type: array items: type: string description: | Filter to mentions in the provided languages, specified as two-letter ISO 639-1 codes. Multiple values are combined with OR logic. example: '[''en'', ''es'']' BotRatings: name: bot_ratings in: query required: false schema: type: array items: type: string enum: - none - further_investigation - very_unlikely - unlikely - potential - likely - very_likely - almost_certain description: > 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. example: '[''likely'', ''very_likely'', ''almost_certain'']' SmartCategories: name: smart_categories in: query required: false schema: type: array items: type: string description: > 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. example: '[''244:c0'', ''294:c1'']' CustomEnrichments: name: custom_enrichments in: query required: false schema: type: array items: type: string description: > 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. example: '[''1681:Substantiated'', ''1681:Mixed'']' MentionTypeSocialMedia: name: mention_type.social_media in: query required: false schema: type: array items: type: string enum: - original_posts - reposts - comments - quoting_posts description: > 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. example: '[''original_posts'', ''reposts'']' MentionTypeNews: name: mention_type.news in: query required: false schema: type: array items: type: string enum: - news description: | 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. example: '[''news'']' MentionTypePodcasts: name: mention_type.podcasts in: query required: false schema: type: array items: type: string enum: - podcasts description: > 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. example: '[''podcasts'']' PublisherGeographySourceCountry: name: publisher_geography.source_country in: query required: false schema: type: array items: type: string description: > 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. example: '[''United States'', ''United Kingdom'']' PublisherGeographySourceRegion: name: publisher_geography.source_region in: query required: false schema: type: array items: type: string enum: - Africa - Americas - Asia - Europe - Oceania description: | Filter by the publisher's geographic region. Primarily applicable to news mentions. Multiple values are combined with OR logic. example: '[''Americas'', ''Europe'']' PublisherGeographySourceSubRegion: name: publisher_geography.source_sub_region in: query required: false schema: type: array items: type: string enum: - 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 description: | Filter by the publisher's geographic subregion. Primarily applicable to news mentions. Multiple values are combined with OR logic. example: '[''Northern America'', ''Northern Europe'']' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````