> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a timeseries-shaped custom metric

> Runs the requested timeseries-shaped custom metric for the project and returns its results; the supplied filter is validated and the metric must be granted by your plan.



## OpenAPI

````yaml https://api.mentionlab.io/api/docs-json post /api/analytics/custom-metrics/timeseries
openapi: 3.0.0
info:
  title: MentionLab Public API v0.5.8-rc
  description: ''
  version: 0.5.8-rc
  contact: {}
servers:
  - url: https://api.mentionlab.io
security: []
tags: []
paths:
  /api/analytics/custom-metrics/timeseries:
    post:
      tags:
        - Analytics - Custom Metrics
      summary: Run a timeseries-shaped custom metric
      description: >-
        Runs the requested timeseries-shaped custom metric for the project and
        returns its results; the supplied filter is validated and the metric
        must be granted by your plan.
      operationId: CustomMetricsController_timeseries
      parameters:
        - name: x-project-id
          in: header
          description: Project ID to specify the project context
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesEnvelope'
        '400':
          description: >-
            The request failed validation — the body, query or path parameters
            are malformed or out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: The request is missing valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: >-
            The authenticated principal lacks the required permission, or access
            to the requested organisation/project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    DispatchRequestDto:
      type: object
      properties:
        metric:
          type: string
          description: >-
            Metric identifier (matches `id` returned by GET
            /analytics/custom-metrics)
          example: sample-metric-table
        filter:
          type: object
          description: >-
            Filter payload. Schema is metric-specific and validated by the
            dispatcher against the registered DTO class.
          additionalProperties: {}
          example:
            from: '2026-01-01'
            to: '2026-01-31'
            limit: 100
      required:
        - metric
    TimeseriesEnvelope:
      type: object
      properties:
        metric:
          type: string
        title:
          type: string
        description:
          type: string
        xAxis:
          $ref: '#/components/schemas/MetricAxisSpec'
        yAxis:
          $ref: '#/components/schemas/MetricAxisSpec'
        series:
          type: array
          items:
            $ref: '#/components/schemas/MetricSeriesSpec'
        points:
          type: array
          description: Time-bucketed data; keys match xAxis.key + each series.key
          items:
            type: object
            additionalProperties: {}
      required:
        - metric
        - title
        - xAxis
        - yAxis
        - series
        - points
    ApiErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code of the error.
          example: 400
        message:
          type: string
          description: >-
            Human-readable description of the error. Validation failures return
            an array of per-field validation errors instead of a single string.
          example: Validation failed
        error:
          type: string
          description: Short name of the HTTP error.
          example: Bad Request
      required:
        - statusCode
    MetricAxisSpec:
      type: object
      properties:
        key:
          type: string
          description: Point key carrying this axis value
        label:
          type: string
        type:
          type: string
          enum:
            - date
            - number
            - percent
          description: Axis value type. 'percent' is a number formatted with a '%' suffix.
      required:
        - key
        - label
        - type
    MetricSeriesSpec:
      type: object
      properties:
        key:
          type: string
          description: Point key carrying this series value
        label:
          type: string
        color:
          type: string
          description: Color hint (semantic palette token, e.g. "primary")
        hidden:
          type: boolean
          description: >-
            Auxiliary series carrying a component value (not for charting);
            generic renderers should skip it
      required:
        - key
        - label

````