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

# Funnel Data

> Returns funnel analysis showing lead progression through conversation
stages, from initial contact to qualification or disqualification.
Requires `analytics:view` permission.




## OpenAPI

````yaml GET /api/analytics/funnel
openapi: 3.1.0
info:
  title: Naturalead Analytics API
  version: 1.0.0
  description: |
    API for retrieving analytics and reporting data in the Naturalead platform.
    Provides overview stats, funnel analysis, campaign performance, and daily
    breakdowns. All endpoints require API key authentication
    and are scoped to the caller's account.
servers:
  - url: '{baseUrl}'
    description: API server
    variables:
      baseUrl:
        default: http://localhost:3001
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Analytics
    description: Analytics and reporting endpoints
paths:
  /api/analytics/funnel:
    get:
      tags:
        - Analytics
      summary: Funnel data
      description: |
        Returns funnel analysis showing lead progression through conversation
        stages, from initial contact to qualification or disqualification.
        Requires `analytics:view` permission.
      operationId: getAnalyticsFunnel
      parameters:
        - $ref: '#/components/parameters/Range'
      responses:
        '200':
          description: Funnel data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunnelData'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    Range:
      name: range
      in: query
      required: false
      description: Time range for analytics data
      schema:
        type: string
        enum:
          - 7d
          - 30d
          - 90d
        default: 30d
  schemas:
    FunnelData:
      type: object
      description: Funnel analysis of lead progression.
      properties:
        stages:
          type: array
          items:
            $ref: '#/components/schemas/FunnelStage'
        totalLeads:
          type: integer
          description: Total leads entering the funnel
        conversionRate:
          type: number
          format: float
          description: Overall funnel conversion rate (qualified / total)
      required:
        - stages
        - totalLeads
        - conversionRate
    FunnelStage:
      type: object
      description: A single stage in the qualification funnel.
      properties:
        stage:
          type: string
          description: Stage name (e.g., contacted, engaged, qualified)
        count:
          type: integer
          description: Number of leads in this stage
        percentage:
          type: number
          format: float
          description: Percentage of total leads that reached this stage
      required:
        - stage
        - count
        - percentage
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  responses:
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Failed to process request
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for programmatic access. Keys use the format `nl_live_<64 hex>`
        or `nl_test_<64 hex>` and are scoped to an account's RBAC permissions.
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token using an API key (format: nl_live_* or nl_test_*).

````