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

# Get Funnel

> Read the conversion through 2 to 5 ordered steps. A step is a page path or a custom event.

Send the steps and the options in a JSON body. The response has one row per step.

```bash theme={null}
curl -sS -X POST "https://api.manalens.dev/v0/projects/$PROJECT_ID/query/funnel" \
  -H "Authorization: Bearer $MANALENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date_from": "2026-11-01",
    "date_to": "2026-11-30",
    "steps": [
      { "type": "page", "value": "/" },
      { "type": "track", "value": "game_started" },
      { "type": "track", "value": "purchase" }
    ],
    "window_seconds": 86400
  }'
```

* A visitor converts when the steps happen in order, within `window_seconds` of the first step.
* `closed` (the default) counts visitors who start at step 1. `open` lets visitors enter at any step.
* `breakdown` splits each step by an event property or a context field.

See [funnels](https://docs.manalens.dev/features/funnels.md).


## OpenAPI

````yaml POST /v0/projects/{projectId}/query/funnel
openapi: 3.1.0
info:
  title: Manalens API
  version: 0.1.0
  description: >-
    The public API of Manalens: event ingestion, profile properties and the
    Query API. Success bodies are the resource, with no envelope. Errors use the
    `Error` format. See https://docs.manalens.dev/api/overview.
servers:
  - url: https://api.manalens.dev
    description: API
  - url: https://events.manalens.dev
    description: Event ingestion
security: []
tags:
  - name: Events
    description: Send website, game and server events
  - name: Profiles
    description: Set and delete profile properties
  - name: Query
    description: Read analytics reports with an API key
paths:
  /v0/projects/{projectId}/query/funnel:
    post:
      tags:
        - Query
      summary: Get funnel
      description: >-
        Conversion through 2 to 5 ordered steps. A step is a page path or a
        custom event. A visitor converts when the steps happen in order within
        the window.
      operationId: getFunnel
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                date_from:
                  description: >-
                    First day (UTC) as YYYY-MM-DD. Default: 29 days before
                    date_to.
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                date_to:
                  description: >-
                    Last day (UTC) as YYYY-MM-DD. Default: today. The range is
                    at most 367 days.
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                page_path:
                  description: Only events on this page path
                  type: string
                  maxLength: 2048
                  pattern: ^\/
                utm_source:
                  type: string
                  maxLength: 255
                utm_medium:
                  type: string
                  maxLength: 255
                utm_campaign:
                  type: string
                  maxLength: 255
                utm_content:
                  type: string
                  maxLength: 255
                utm_term:
                  type: string
                  maxLength: 255
                ref:
                  description: Referral code (`ref` link parameter)
                  type: string
                  maxLength: 255
                paid_source:
                  description: Ad network of a paid click
                  type: string
                  enum:
                    - google
                    - meta
                    - microsoft
                    - tiktok
                    - twitter
                    - linkedin
                    - reddit
                    - snapchat
                    - paid_utm
                click_id:
                  description: Ad click ID (gclid, fbclid and others)
                  type: string
                  maxLength: 255
                channel_type:
                  description: Acquisition channel
                  type: string
                  enum:
                    - Paid Search
                    - Paid Video
                    - Paid Social
                    - Paid Other
                    - Email
                    - Referrals
                    - Display
                    - AI
                    - Organic Search
                    - Organic Social
                    - Organic Video
                    - Referrers
                    - Direct
                referrer:
                  description: Referrer origin, for example https://www.reddit.com
                  type: string
                  maxLength: 2048
                locale:
                  type: string
                  maxLength: 32
                device:
                  type: string
                  enum:
                    - desktop
                    - mobile
                    - tablet
                    - bot
                os:
                  type: string
                  enum:
                    - windows
                    - macos
                    - ios
                    - android
                    - linux
                    - other
                browser:
                  type: string
                  enum:
                    - chrome
                    - safari
                    - firefox
                    - edge
                    - opera
                    - other
                country:
                  description: ISO 3166-1 alpha-2 country code
                  type: string
                  pattern: ^[A-Za-z]{2}$
                currency:
                  description: 'Report currency for revenue (ISO 4217). Default: USD.'
                  type: string
                  pattern: ^[A-Z]{3}$
                currency_mode:
                  description: >-
                    `convert` (default) converts other currencies with the rate
                    of the event day. `only` counts the report currency alone.
                  type: string
                  enum:
                    - convert
                    - only
                filters:
                  description: Operator filters, combined with AND
                  maxItems: 20
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: >-
                          A context field (utm_source, referrer, channel_type,
                          country, ...), page_path, event, or properties.<key>
                      op:
                        type: string
                        enum:
                          - eq
                          - neq
                          - in
                          - nin
                          - gt
                          - lt
                          - gte
                          - lte
                          - startsWith
                          - endsWith
                          - contains
                          - notEmpty
                          - isEmpty
                      value:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                    required:
                      - field
                      - op
                steps:
                  minItems: 2
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - page
                          - track
                      value:
                        type: string
                        minLength: 1
                        maxLength: 2048
                      filters: {}
                    required:
                      - type
                      - value
                    additionalProperties: false
                  description: >-
                    2 to 5 steps: `{ "type": "page", "value": "/pricing" }` or
                    `{ "type": "track", "value": "signup" }`
                window_seconds:
                  description: >-
                    Conversion window in seconds: 1 minute to 90 days. Default:
                    86400.
                  type: integer
                  minimum: 60
                  maximum: 7776000
                funnel_type:
                  description: >-
                    `closed` (default) counts visitors who start at step 1.
                    `open` lets visitors enter at any step.
                  type: string
                  enum:
                    - closed
                    - open
                breakdown:
                  description: Split the funnel by an event property or a context field
                  type: string
                  pattern: ^[A-Za-z0-9_.:$ -]{1,100}$
                breakdown_touch:
                  description: >-
                    With breakdown: the value of the first (default) or the last
                    touch
                  type: string
                  enum:
                    - first
                    - last
              required:
                - steps
      responses:
        '200':
          description: The report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportRows'
        '400':
          description: >-
            `INVALID_QUERY`: a parameter or the body is not valid. The message
            names the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `UNAUTHORIZED`: the API key is missing, malformed, unknown or
            revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            `SUBSCRIPTION_REQUIRED`: the workspace has no active subscription or
            trial. `PLAN_UPGRADE_REQUIRED`: API keys need the Scale plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `FORBIDDEN`: the key does not have the scope, its creator left the
            workspace, or the request came from a browser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `NOT_FOUND`: the key belongs to another project, or the resource
            does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`TOO_MANY_REQUESTS`: the key or workspace budget is used up'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before a retry
              schema:
                type: integer
        '500':
          description: '`INTERNAL`: an unexpected error. The body has a `request_id`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKey: []
components:
  schemas:
    ReportRows:
      type: object
      properties:
        date_from:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: First day of the report
        date_to:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Last day of the report
        rows:
          type: array
          items:
            type: object
            propertyNames:
              type: string
            additionalProperties: {}
      required:
        - date_from
        - date_to
        - rows
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable code. Branch on it.
            message:
              type: string
              description: A human-readable text. The wording can change.
            request_id:
              description: 'INTERNAL only: quote it when you contact support'
              type: string
          required:
            - code
            - message
      required:
        - error
      description: >-
        The error format of every endpoint. See
        https://docs.manalens.dev/api/errors.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        An API key (`mana_api_...`) with scopes. It reads reports and writes
        profile properties.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.