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

# Stage Distribution

> Returns how many leads currently sit in each conversation stage,
grouped by agent. Stages are free-form per agent config — not a
global taxonomy. Uses the latest non-archived conversation per lead
within the time range.
Requires `analytics:view` permission.




## OpenAPI

````yaml GET /api/analytics/stage-distribution
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,
    campaign performance, 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/stage-distribution:
    get:
      tags:
        - Analytics
      summary: Journey stage distribution
      description: |
        Returns how many leads currently sit in each conversation stage,
        grouped by agent. Stages are free-form per agent config — not a
        global taxonomy. Uses the latest non-archived conversation per lead
        within the time range.
        Requires `analytics:view` permission.
      operationId: getStageDistribution
      parameters:
        - $ref: '#/components/parameters/Range'
        - name: agentConfigId
          in: query
          required: false
          description: Limit results to a single agent config
          schema:
            type: string
      responses:
        '200':
          description: Stage distribution by agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageDistribution'
        '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:
    StageDistribution:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentStageDistribution'
      required:
        - agents
    AgentStageDistribution:
      type: object
      properties:
        agentConfigId:
          type: string
        agentName:
          type: string
        stages:
          type: array
          items:
            $ref: '#/components/schemas/StageCount'
      required:
        - agentConfigId
        - agentName
        - stages
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    StageCount:
      type: object
      properties:
        stageId:
          type: string
          nullable: true
        stageName:
          type: string
        count:
          type: integer
      required:
        - stageName
        - count
  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_*).

````