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

# Get Stats

`POST /api/stats`

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.net/octanist/apis/octanist-api.md) · [All operations](https://skmtc.net/octanist/apis/octanist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octanist/octanist-api/revisions/a0620637a051/schema)