> ## 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 Top Events

> Top events by frequency over the selected window.

Returns the most frequently fired events in the project, by total event count.

Pass `type=custom` to restrict results to custom events (events tracked via `formo.track(...)`). This replaces the previous `top_custom_events` endpoint.


## OpenAPI

````yaml GET /v0/top_events
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.** All endpoints require a workspace API key with the appropriate
    scopes (see `x-api-scopes`).


    **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.** Every non-2xx response uses the `Error` envelope: `{ 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 POST/PUT/PATCH/DELETE
    to make retries safe; the response is cached for 24 h and replayed on
    duplicate keys.
  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/top_events:
    get:
      tags:
        - Query
      summary: Get top events by frequency
      description: >-
        Most frequent events in the project. By default returns all event
        categories (page / track / identify / decoded_log / etc.). Pass
        `type=custom` to filter to custom track events only.
      operationId: getAnalyticsTopEvents
      parameters:
        - $ref: '#/components/parameters/AnalyticsDateFrom'
        - $ref: '#/components/parameters/AnalyticsDateTo'
        - $ref: '#/components/parameters/AnalyticsFilters'
        - $ref: '#/components/parameters/AnalyticsLimit'
        - $ref: '#/components/parameters/AnalyticsOffset'
        - name: type
          in: query
          schema:
            type: string
            enum:
              - custom
          description: >-
            Pass 'custom' to filter to custom track events only (events with
            type='track' and a non-empty event name). Omit for all events.
      responses:
        '200':
          description: Top events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
              example:
                meta:
                  - name: project_id
                    type: String
                  - name: type
                    type: String
                  - name: event
                    type: String
                  - name: hits
                    type: UInt64
                data:
                  - project_id: proj_abc
                    type: page
                    event: ''
                    hits: 4128
                  - project_id: proj_abc
                    type: identify
                    event: ''
                    hits: 1284
                  - project_id: proj_abc
                    type: track
                    event: wallet_connect
                    hits: 612
                  - project_id: proj_abc
                    type: track
                    event: swap
                    hits: 248
                  - project_id: proj_abc
                    type: track
                    event: stake
                    hits: 86
                rows: 5
                rows_before_limit_at_least: 14
        '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. Each entry
        is `{ field, op, value }`. Use `in` / `notIn` with a pipe-delimited
        `value` (e.g. `"chrome|firefox"`) for multi-value matching.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AnalyticsFilterCondition'
          example:
            - field: location
              op: equals
              value: US
            - field: device
              op: in
              value: desktop|mobile
    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.
    AnalyticsFilterCondition:
      type: object
      description: >-
        A single analytics filter condition. Use `in` / `notIn` with a
        pipe-delimited string value (e.g. `"a|b|c"`) for multi-value matches.
      properties:
        field:
          type: string
          description: >-
            Column to filter on. Standard session columns: `device`, `browser`,
            `os`, `location`, `referrer`, `ref`, `origin`, `utm_source`,
            `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`. Track-event
            columns: `event`, `type`. Numeric event properties: `volume`,
            `revenue`, `points`.
        op:
          type: string
          enum:
            - equals
            - notEquals
            - greater
            - less
            - greaterOrEqual
            - lessOrEqual
            - in
            - notIn
          description: Comparison operator.
        value:
          oneOf:
            - type: string
            - type: number
            - type: boolean
          description: >-
            Value to compare against. For `in` / `notIn`, pass a pipe-delimited
            string (e.g. `"chrome|firefox"`).
      required:
        - field
        - op
        - value
    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 Keys.

````