Skip to main content
POST
/
api
/
stats
Get Stats
curl --request POST \
  --url https://octanist.com/api/stats \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "period": "current",
  "startDate": "2026-01-01",
  "endDate": "2026-03-01"
}
'
{
  "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"
  }
}

​
Request Body

FieldTypeRequiredDefaultDescription
periodstringNocurrentPeriod: current, previous, custom
startDatestringIf custom-Start date (YYYY-MM-DD)
endDatestringIf custom-End date (YYYY-MM-DD)
A JSON body is required, even if empty ({}). Sending no body returns a 400 error.

​
Example Request

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

{
  "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"
  }
}
The periodStart and periodEnd fields in the usage object will be null if there is no active subscription.

​
Error Responses

StatusCodeDescription
400VALIDATION_ERRORInvalid request body, or missing dates for custom period
400INVALID_DATEInvalid date format (use YYYY-MM-DD)
401UNAUTHORIZEDMissing or invalid API key
500INTERNAL_ERRORServer error

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Body

application/json

Stats request parameters

​
period
enum<string>
default:current

Period to retrieve statistics for

Available options:
current,
previous,
custom
​
startDate
string<date>

Start date (YYYY-MM-DD). Required when period is custom.

Example:

"2026-01-01"

​
endDate
string<date>

End date (YYYY-MM-DD). Required when period is custom.

Example:

"2026-03-01"

Response

Statistics retrieved successfully

​
success
boolean
Example:

true

​
data
object
​
meta
object