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

# Get Stats

> Retrieve dashboard statistics including usage, lead counts, and conversion metrics

## Request Body

| Field       | Type   | Required  | Default   | Description                             |
| ----------- | ------ | --------- | --------- | --------------------------------------- |
| `period`    | string | No        | `current` | Period: `current`, `previous`, `custom` |
| `startDate` | string | If custom | -         | Start date (YYYY-MM-DD)                 |
| `endDate`   | string | If custom | -         | End date (YYYY-MM-DD)                   |

A JSON body is required, even if empty (`{}`). Sending no body returns a `400` error.

## Example Request

```bash theme={null}
curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"period": "current"}' \
  "https://octanist.com/api/stats"
```

## Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "usage": {
      "leadsUsed": 150,
      "leadsLimit": 500,
      "lockedLeads": 0,
      "periodStart": "2026-01-01T00:00:00.000Z",
      "periodEnd": "2026-03-01T23:59:59.999Z"
    },
    "leads": {
      "total": 150,
      "byStatus": {
        "open": 45,
        "qualified": 30,
        "won": 50,
        "lost": 25
      },
      "bySource": {
        "gtm": 120,
        "api": 20,
        "manual": 10
      }
    },
    "conversion": {
      "qualified": 80,
      "qualificationRate": 0.7,
      "winRate": 0.625,
      "averageValue": 2500,
      "totalValue": 125000
    }
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}
```

<Note>
  The `periodStart` and `periodEnd` fields in the usage object will be `null` if there is no active subscription.
</Note>

## Error Responses

| Status | Code               | Description                                              |
| ------ | ------------------ | -------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Invalid request body, or missing dates for custom period |
| 400    | `INVALID_DATE`     | Invalid date format (use YYYY-MM-DD)                     |
| 401    | `UNAUTHORIZED`     | Missing or invalid API key                               |
| 500    | `INTERNAL_ERROR`   | Server error                                             |


## OpenAPI

````yaml POST /api/stats
openapi: 3.0.1
info:
  title: Octanist API
  description: >-
    The Octanist API allows you to manage leads, retrieve statistics, and access
    ad spend data.
  version: 2.2.0
  contact:
    name: Octanist Support
    url: https://octanist.com/docs
servers:
  - url: https://octanist.com
    description: Production server
security:
  - apiKeyAuth: []
paths:
  /api/stats:
    post:
      tags:
        - Analytics
      summary: Get Stats
      description: >-
        Retrieve dashboard statistics including usage, lead counts, and
        conversion metrics. A JSON body is required, even if empty (`{}`).
      requestBody:
        description: Stats request parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatsRequest'
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/StatsData'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          description: >-
            Invalid request body, missing dates for custom period, or invalid
            date format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StatsRequest:
      type: object
      properties:
        period:
          type: string
          enum:
            - current
            - previous
            - custom
          default: current
          description: Period to retrieve statistics for
        startDate:
          type: string
          format: date
          description: Start date (YYYY-MM-DD). Required when period is `custom`.
          example: '2026-01-01'
        endDate:
          type: string
          format: date
          description: End date (YYYY-MM-DD). Required when period is `custom`.
          example: '2026-03-01'
    StatsData:
      type: object
      properties:
        usage:
          type: object
          properties:
            leadsUsed:
              type: integer
              example: 150
            leadsLimit:
              type: integer
              example: 500
            lockedLeads:
              type: integer
              example: 0
            periodStart:
              type: string
              format: date-time
              nullable: true
              description: Null if no active subscription
              example: '2026-01-01T00:00:00.000Z'
            periodEnd:
              type: string
              format: date-time
              nullable: true
              description: Null if no active subscription
              example: '2026-03-01T23:59:59.999Z'
        leads:
          type: object
          properties:
            total:
              type: integer
              example: 150
            byStatus:
              type: object
              properties:
                open:
                  type: integer
                  example: 45
                qualified:
                  type: integer
                  example: 30
                won:
                  type: integer
                  example: 50
                lost:
                  type: integer
                  example: 25
            bySource:
              type: object
              additionalProperties:
                type: integer
              example:
                gtm: 120
                api: 20
                manual: 10
        conversion:
          type: object
          properties:
            qualified:
              type: integer
              example: 80
            qualificationRate:
              type: number
              example: 0.7
            winRate:
              type: number
              example: 0.625
            averageValue:
              type: number
              example: 2500
            totalValue:
              type: number
              example: 125000
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6
        timestamp:
          type: string
          format: date-time
          example: '2026-03-10T12:00:00.000Z'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human readable error message
              example: Human readable error message
            details:
              type: object
              description: Optional additional error details
        meta:
          $ref: '#/components/schemas/Meta'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````