---
title: "Get Stats"
method: POST
path: "/api/stats"
tags: ["Analytics"]
---

# Get Stats

`POST /api/stats`

## Request

- Base URL: `https://octanist.com`
- URL: `https://octanist.com/api/stats`
- Auth: API key in header `X-API-KEY`

Retrieve dashboard statistics including usage, lead counts, and conversion metrics. A JSON body is required, even if empty (`{}`).

## Request body

- StatsRequest
  - `period` 'current' | 'previous' | 'custom': Period to retrieve statistics for
  - `startDate` string, date: Start date (YYYY-MM-DD). Required when period is `custom`.
  - `endDate` string, date: End date (YYYY-MM-DD). Required when period is `custom`.

## Response `200`

Statistics retrieved successfully

- object
  - `success` boolean
  - `data` StatsData
    - `usage` object
      - `leadsUsed` integer
      - `leadsLimit` integer
      - `lockedLeads` integer
      - `periodStart` string, date-time, nullable: Null if no active subscription
      - `periodEnd` string, date-time, nullable: Null if no active subscription
    - `leads` object
      - `total` integer
      - `byStatus` object
        - `open` integer
        - `qualified` integer
        - `won` integer
        - `lost` integer
      - `bySource` object
    - `conversion` object
      - `qualified` integer
      - `qualificationRate` number
      - `winRate` number
      - `averageValue` number
      - `totalValue` number
  - `meta` Meta
    - `requestId` string
    - `timestamp` string, date-time

## Other responses

- `400`: Invalid request body, missing dates for custom period, or invalid date format
- `401`: Missing or invalid API key
- `500`: Server error

---

[API](https://skmtc.dev/octanist/apis/octanist-api.md) - [All operations](https://skmtc.dev/octanist/apis/octanist-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octanist/apis/octanist-api/revisions/29a41aff4975?raw)
