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

# Get Volume by Metric

> Transaction volume grouped by a chosen column (e.g. pathname, referrer).

Returns total transaction volume broken down by `metric_column`. The required `metric_column` query parameter selects the dimension - for example `pathname`, `referrer`, `utm_source`, or `location`. Use `paid_source` to group by acquiring ad network (per-event sticky attribution; rows with no paid touch are excluded).


## OpenAPI

````yaml GET /v0/volume_by_metric
openapi: 3.1.0
info:
  title: Formo Public API
  description: >-
    REST API for managing Formo projects, analytics, alerts, boards, charts,
    contracts, segments, and AI chat.


    **Auth.** Every endpoint on `api.formo.so` requires a workspace API key with
    the appropriate scopes (see `x-api-scopes`). The one exception is `POST
    /v0/raw_events`, which runs on `events.formo.so` and authenticates with the
    project SDK write key instead.


    **Response shape.** Successful responses return the resource directly (or `{
    data: [...], total, page, size, has_more }` for paginated lists). HTTP
    status carries success/failure; there is no envelope wrapping success
    bodies.


    **Errors.** Non-2xx responses from `api.formo.so` use the `Error` envelope,
    with two exceptions: some rate-limit rejections reply in plain text, and
    `POST /v0/raw_events` returns a plain `{ "error": "..." }` object. Treat the
    HTTP status as authoritative and parse defensively: `{ error: { code,
    message, doc_url, param?, details? } }`. Branch on the machine-readable
    `code` (see `ErrorCode` enum) and follow `doc_url` to the matching section
    of the [errors reference](https://docs.formo.so/api/errors).


    **Idempotency.** Pass an `Idempotency-Key` header on write requests to
    alerts, boards, charts, contracts, segments, and import to make retries
    safe; the response is cached for 24 h and replayed on duplicate keys.
    Profile writes and `POST /v0/query` do not support it.
  version: 0.1.0
  contact:
    name: Formo
    url: https://formo.so
servers:
  - url: https://api.formo.so
    description: API Server (boards, alerts, contracts, segments, profiles, query, import)
  - url: https://events.formo.so
    description: Events Server (event ingestion)
security:
  - WorkspaceApiKey: []
tags:
  - name: Alerts
    description: Manage project alerts and notifications
  - name: Boards
    description: Manage dashboard boards
  - name: Charts
    description: Manage charts within boards
  - name: Contracts
    description: Manage blockchain contract monitoring
  - name: Segments
    description: Manage user segments
  - name: Profiles
    description: Wallet profiles and import
  - name: Query
    description: >-
      Execute SQL queries and call pre-built analytics endpoints (KPIs, top
      pages, lifecycle, retention, revenue). Requires the query:read scope.
  - name: Events
    description: Event ingestion API (events.formo.so)
paths:
  /v0/volume_by_metric:
    get:
      tags:
        - Query
      summary: Get transaction volume grouped by a chosen column
      operationId: getAnalyticsVolumeByMetric
      parameters:
        - $ref: '#/components/parameters/AnalyticsDateFrom'
        - $ref: '#/components/parameters/AnalyticsDateTo'
        - $ref: '#/components/parameters/AnalyticsFilters'
        - $ref: '#/components/parameters/AnalyticsPageScope'
        - name: metric_column
          in: query
          required: true
          schema:
            type: string
            enum:
              - pathname
              - origin
              - channel
              - paid_source
              - referrer
              - referrer_url
              - ref
              - utm_source
              - utm_medium
              - utm_campaign
              - utm_content
              - utm_term
              - builder_codes
              - location
              - device
              - browser
              - os
              - rdns
              - provider_name
              - chain_id
              - event
          description: >-
            Column to group volume by. Use `channel` for the 13-channel
            acquisition classifier (see the [channel classification
            table](https://docs.formo.so/features/attribution/key-metrics#channels)).
            Use `paid_source` for the acquiring ad network (per-event sticky
            attribution; paid rows only, see [Ad
            attribution](https://docs.formo.so/features/attribution/ads)).
            Unknown values return zero rows.
        - $ref: '#/components/parameters/AnalyticsLimit'
        - $ref: '#/components/parameters/AnalyticsOffset'
      responses:
        '200':
          description: Volume by metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
              example:
                meta:
                  - name: project_id
                    type: String
                  - name: pathname
                    type: String
                  - name: sum_volume
                    type: Float64
                data:
                  - project_id: proj_abc
                    pathname: app.example.com/trade
                    sum_volume: 2812400
                  - project_id: proj_abc
                    pathname: app.example.com/earn
                    sum_volume: 612300
                  - project_id: proj_abc
                    pathname: app.example.com/swap
                    sum_volume: 412800
                rows: 3
                rows_before_limit_at_least: 8
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiError'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestApiError'
components:
  parameters:
    AnalyticsDateFrom:
      name: date_from
      in: query
      schema:
        type: string
        format: date
      description: Inclusive start date (YYYY-MM-DD). Defaults to 7 days before date_to.
    AnalyticsDateTo:
      name: date_to
      in: query
      schema:
        type: string
        format: date
      description: Inclusive end date (YYYY-MM-DD). Defaults to today.
    AnalyticsFilters:
      name: filters
      in: query
      description: >-
        Array of filter conditions, JSON-encoded in the query string. Entries
        use `{ field, op, value }` and are combined with implicit AND. For
        example, filter traffic referred by Google with
        `[{"field":"referrer","op":"contains","value":"google"}]`, or filter a
        page with `[{"field":"page","op":"eq","value":"/pricing"}]`. For `in` /
        `nin`, pass a non-empty array value such as `["chrome","firefox"]` or a
        pipe-delimited string such as `"chrome|firefox"`. Array string members
        cannot contain a literal `|`, which is reserved as the Tinybird
        membership separator. Optional one-level nested `filters` use the same
        canonical envelope and membership rule. On the user-aggregate endpoints
        (lifecycle, frequency) the same array also carries profile-family
        entries: profile metrics (net_worth_usd, volume, revenue, points),
        social identity fields, a lifecycle entry
        ({"field":"lifecycle","op":"in","value":"New|Power user"}), and resource
        entries using the stable fields chains.balance, apps.balance,
        tokens.balance, and labels.value with named qualifier properties
        (chain_id, app_id, token_address, scope, tag_id). The retired per-family
        parameters (socials, chain_filters, app_filters, token_filters,
        label_filters, profile_filters, lifecycle_filter) are rejected. Overview
        also accepts raw Data source filters with `field` set to `channel`, ops
        `eq`/`neq`/`in`/`nin`, and values `web`, `mobile`, `api`, `import`,
        `server`, `onchain`; this is distinct from acquisition Channel
        (`channel_type`) and the two can be combined.
      schema:
        type: string
      example: '[{"field":"referrer","op":"contains","value":"google"}]'
    AnalyticsPageScope:
      name: page_scope
      in: query
      schema:
        type: string
        enum:
          - page
          - session
        default: page
      description: >-
        Controls how a `page` filter is interpreted. `page` (default) scopes
        metrics to activity on the filtered page. On `/v0/kpis`, `pageviews`
        counts only views of the filtered page, while `bounce_rate` and
        `avg_session_sec` are entry-page metrics for sessions that landed there.
        `session` preserves the legacy session scope: metrics include all
        relevant activity in any session that viewed the page. `sessions` and
        `visitors` are unchanged between scopes. This parameter only affects
        requests that include a `page` filter. It is distinct from
        `/v0/top_pages` `mode`, which selects the all, entry, or exit page-flow
        view.
      example: page
    AnalyticsLimit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 1000
      description: Maximum results to return (default 50, max 1000)
    AnalyticsOffset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 100000
      description: Number of results to skip for pagination (default 0)
  schemas:
    AnalyticsResponse:
      type: object
      description: >-
        Analytics endpoint response. The `data` array contains the rows; the
        exact row shape depends on the endpoint. `meta` carries column type
        information for rendering, `rows` is the row count, and `statistics`
        holds query timing metadata.
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        meta:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        rows:
          type: integer
        rows_before_limit_at_least:
          type: integer
        statistics:
          type: object
          additionalProperties: true
    RestApiError:
      $ref: '#/components/schemas/Error'
      description: >-
        Deprecated alias for `Error`. Existing endpoint specs reference this
        name; new specs should reference `Error` directly.
    Error:
      type: object
      description: >-
        Standard error envelope returned by every public API endpoint for any
        non-2xx response. The HTTP status code carries success/failure; the body
        provides a machine-readable `code`, a human-readable `message`, and a
        `doc_url` pointing at the matching section of the docs so agents can
        fetch context on the fly.
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: >-
                Human-readable error description. Wording may change between
                releases, so branch on `code`, not `message`.
            doc_url:
              type: string
              format: uri
              description: >-
                Link to the matching section of the errors reference at
                https://docs.formo.so/api/errors.
            param:
              type: string
              description: >-
                When the error pertains to a specific request field, the dotted
                path to that field (e.g. `body.trigger_filters.0.value`).
            details:
              type: object
              additionalProperties: true
              description: >-
                Code-specific extra context. For `INVALID_VALIDATION_REQUEST`
                this is a `{ fieldPath: message }` map of every Zod validation
                failure.
      required:
        - error
    ErrorCode:
      type: string
      description: >-
        Stable, enumerated error codes. New codes may be added in any release;
        clients should treat unknown codes as the closest matching HTTP status
        family.
      enum:
        - INTERNAL_SERVER_ERROR
        - INVALID_VALIDATION_REQUEST
        - UNAUTHORIZED
        - BAD_REQUEST
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - INVALID_CHAIN_ID
        - CONTEXT_LIMIT_EXCEEDED
        - SERVICE_UNAVAILABLE
        - TOO_MANY_REQUESTS
        - IDEMPOTENCY_IN_PROGRESS
        - INVALID_IDEMPOTENCY_KEY
  securitySchemes:
    WorkspaceApiKey:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard
        under Team Settings > API.

````