> ## 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 volume over time > Returns mention volume aggregated into time buckets over the requested date range. Use the optional `group_by` parameter to add a secondary breakdown within each bucket by any filterable dimension (e.g., channel, language, bot rating, smart category, etc.). All standard mention filters can be applied to narrow the results. ## OpenAPI ````yaml /api/api_docs.yaml get /workspaces/{workspaceId}/analytics/timeline 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}/analytics/timeline: get: tags: - Workspaces summary: Mention volume over time description: > Returns mention volume aggregated into time buckets over the requested date range. Use the optional `group_by` parameter to add a secondary breakdown within each bucket by any filterable dimension (e.g., channel, language, bot rating, smart category, etc.). 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/GroupByTimeline' - $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 time-bucketed mention volume. content: application/json: schema: type: object properties: totalCount: type: integer minimum: 0 description: > Total count of all mentions matching the filters across all time buckets. example: 125000 buckets: type: array description: | Mention volume aggregated into daily buckets over the requested date range. items: type: object properties: date: type: string format: date-time description: The start of the time bucket (midnight UTC). example: '2025-01-15T00:00:00Z' count: type: integer minimum: 0 description: >- Total number of mentions published during this bucket. groups: type: array description: | Secondary breakdown by the `group_by` dimension. Only present when `group_by` is specified. Each entry represents one option value within the dimension. items: type: object properties: key: type: string description: > The option value for this group (e.g., `"news"`, `"en"`, `"almost_certain"`). count: type: integer minimum: 0 description: >- Number of mentions in this group for this bucket. '400': description: Invalid `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' GroupByTimeline: name: group_by in: query required: false schema: type: string description: > Adds a secondary breakdown within each time bucket by the specified dimension. 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 - `bot_ratings` — Mention counts by bot detection confidence - `mention_type.social_media` — Mention counts by social media post type - `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`. When omitted, each bucket contains only the total mention count. When provided, each bucket includes a `groups` array with counts broken down by the dimension's option values. 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 ````