> ## 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.

# Agent Funnels

> Cohort funnel for every agent in the account. The cohort is the
non-archived conversations started in the window; each one is traced
through its `stage_transitioned` events up to now. Returns the agent's
stage graph (as drawn in the agent editor) alongside how many
conversations reached each stage, which edges they took, and where they
are now. Agents with no conversations are included with zero counts.
Requires `analytics:view` permission.




## OpenAPI

````yaml GET /api/analytics/agent-funnels
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, outreach funnel, journey stage distribution,
    and daily breakdowns. All endpoints require API key
    authentication and are scoped to the caller's account.
servers:
  - url: https://api.naturalead.ai
    description: Production
  - url: http://localhost:3001
    description: Local development
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Analytics
    description: Analytics and reporting endpoints
paths:
  /api/analytics/agent-funnels:
    get:
      tags:
        - Analytics
      summary: Per-agent journey funnels
      description: |
        Cohort funnel for every agent in the account. The cohort is the
        non-archived conversations started in the window; each one is traced
        through its `stage_transitioned` events up to now. Returns the agent's
        stage graph (as drawn in the agent editor) alongside how many
        conversations reached each stage, which edges they took, and where they
        are now. Agents with no conversations are included with zero counts.
        Requires `analytics:view` permission.
      operationId: getAgentFunnels
      parameters:
        - $ref: '#/components/parameters/Range'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Tz'
      responses:
        '200':
          description: Agent funnels
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentFunnel'
                required:
                  - agents
        '400':
          description: Invalid `from` / `to`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    Range:
      name: range
      in: query
      required: false
      description: |
        Shorthand window ending now. Ignored when `from` or `to` is given.
      schema:
        type: string
        enum:
          - 7d
          - 30d
          - 90d
        default: 30d
    From:
      name: from
      in: query
      required: false
      description: Inclusive start of the window (ISO-8601 timestamp).
      schema:
        type: string
        format: date-time
    To:
      name: to
      in: query
      required: false
      description: |
        Exclusive end of the window (ISO-8601 timestamp). Defaults to now.
        The window may span at most 366 days.
      schema:
        type: string
        format: date-time
    Tz:
      name: tz
      in: query
      required: false
      description: IANA timezone used to bucket `/daily`. Unknown values fall back to UTC.
      schema:
        type: string
        example: Asia/Jerusalem
  schemas:
    AgentFunnel:
      type: object
      properties:
        agentConfigId:
          type: string
        agentName:
          type: string
        agentStatus:
          type: string
          enum:
            - active
            - inactive
            - draft
        stages:
          type: array
          description: The agent's stage graph, with editor canvas positions when saved
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              order:
                type: integer
              nextStages:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    condition:
                      type: string
              nextStageIds:
                type: array
                items:
                  type: string
              position:
                type: object
                properties:
                  x:
                    type: number
                  'y':
                    type: number
        inboundEntries:
          type: array
          items:
            type: object
            properties:
              targetStageId:
                type: string
              condition:
                type: string
        totals:
          type: object
          properties:
            conversations:
              type: integer
            replied:
              type: integer
            active:
              type: integer
            completed:
              type: integer
            handedOff:
              type: integer
            dropped:
              type: integer
            unmapped:
              type: integer
              description: Conversations whose stages were since removed from the agent
        stageStats:
          type: array
          items:
            type: object
            properties:
              stageId:
                type: string
              reached:
                type: integer
                description: Conversations that were in this stage at any point
              entered:
                type: integer
                description: Conversations that opened on this stage
              active:
                type: integer
                description: Still active and currently in this stage
              completed:
                type: integer
              handedOff:
                type: integer
              dropped:
                type: integer
        edgeStats:
          type: array
          description: >-
            Conversations that moved along each edge (counted once per
            conversation)
          items:
            type: object
            properties:
              source:
                type: string
              target:
                type: string
              count:
                type: integer
    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_*).

````

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