> ## 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. # Mention count distribution > Returns mention counts broken down by a specified dimension. Use the `group_by` parameter to select which dimension to distribute by (e.g., channels, authors, domains, or languages). All standard mention filters can be applied to narrow the results. ## OpenAPI ````yaml /api/api_docs.yaml get /workspaces/{workspaceId}/analytics/distribution 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: 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. Custom enrichments are provisioned by PeakMetrics staff for your team — contact support@peakmetrics.com to get them set up. Once provisioned, you can list your team's custom enrichments with `GET /customEnrichments` and push values for individual mentions with `PUT /mentions/customEnrichments`. paths: /workspaces/{workspaceId}/analytics/distribution: get: tags: - Workspaces summary: Mention count distribution description: | Returns mention counts broken down by a specified dimension. Use the `group_by` parameter to select which dimension to distribute by (e.g., channels, authors, domains, or languages). All standard mention filters can be applied to narrow the results. parameters: - $ref: '#/components/parameters/WorkspaceId' - $ref: '#/components/parameters/Since' - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/GroupByDistribution' - $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 object containing the mention count distribution. content: application/json: schema: type: object properties: groupBy: type: string description: The dimension used for this distribution. example: channels totalCount: type: integer minimum: 0 description: > Total count of all mentions matching the filters. This may be larger than the sum of group counts if the dimension has many distinct values. example: 125000 groups: type: array description: | Mention counts for each value within the specified dimension, sorted by count descending. items: type: object properties: key: type: string description: | The option value for this group (e.g., `"twitter"`, `"nytimes.com"`, `"en"`). example: twitter name: type: string description: | Human-readable label for this group, if available (e.g., `"English"` for language code `"en"`). example: X (Twitter) count: type: integer minimum: 0 description: Number of mentions in this group. example: 31440 percentage: type: number format: float minimum: 0 maximum: 100 description: > Percentage of total mentions that this group represents, calculated as (count / totalCount) * 100. example: 25.15 '400': description: Invalid or missing `group_by` value, or other invalid parameters. '404': description: Workspace not found or user does not have access. 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' GroupByDistribution: name: group_by in: query required: true schema: type: string description: > The dimension to distribute mention counts by. 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 - `authors` — Top authors by mention count - `domains` — Top domains by mention count - `languages` — Mention counts by detected language - `bot_ratings` — Mention counts by bot detection confidence - `publisher_geography.source_country` — Mention counts by publisher country - `publisher_geography.source_region` — Mention counts by publisher region - `publisher_geography.source_sub_region` — Mention counts by publisher 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`. example: channels 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 ````