> ## 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 table-shaped custom metric

> Runs the requested table-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/table
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/table:
    post:
      tags:
        - Analytics - Custom Metrics
      summary: Run a table-shaped custom metric
      description: >-
        Runs the requested table-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_table
      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/TableEnvelope'
        '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
    TableEnvelope:
      type: object
      properties:
        metric:
          type: string
          description: Metric id (matches discovery list)
        title:
          type: string
          description: Human-readable card title
        description:
          type: string
          description: Short description rendered under the title
        columns:
          type: array
          items:
            $ref: '#/components/schemas/MetricColumnSpec'
        rows:
          type: array
          description: Row data; keys match `columns[].key`
          items:
            type: object
            additionalProperties: {}
        defaultSort:
          $ref: '#/components/schemas/MetricDefaultSort'
        highlight:
          description: Row-level highlight rule (e.g. tint the leader row)
          allOf:
            - $ref: '#/components/schemas/MetricHighlightRule'
      required:
        - metric
        - title
        - columns
        - rows
    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
    MetricColumnSpec:
      type: object
      properties:
        key:
          type: string
          description: Row key this column reads from
        label:
          type: string
          description: Human-readable header label
        type:
          type: string
          enum:
            - text
            - number
            - percent
            - entity
            - date
        decimals:
          type: number
          description: Decimal places for `number` / `percent` columns
        nullLabel:
          type: string
          description: Rendered in place of null/undefined values
          example: —
        tooltip:
          type: string
          description: >-
            Explanatory copy shown on hover over the column header. Generic
            renderers surface it as a header tooltip; omit for self-evident
            columns.
        hidden:
          type: boolean
          description: >-
            Auxiliary column carrying a component value (not for display);
            generic renderers should skip it
      required:
        - key
        - label
        - type
    MetricDefaultSort:
      type: object
      properties:
        column:
          type: string
          description: Column key to sort by initially
        order:
          type: string
          enum:
            - asc
            - desc
      required:
        - column
        - order
    MetricHighlightRule:
      type: object
      properties:
        column:
          type: string
          description: >-
            Column key the rule applies to. For 'max'/'min' rules this is a
            numeric column; for 'entity' it is an `entity`-typed column.
        rule:
          type: string
          enum:
            - max
            - min
            - entity
          description: >-
            How to pick the highlighted row. 'max'/'min' pick the row with the
            extremum value in `column`. 'entity' delegates to the frontend,
            which highlights the active 'view as' brand (if set) or otherwise
            the primary-flagged entity.
      required:
        - column
        - rule

````