---
title: "Returns the caller's usage overview: verdict breakdown, activity series, check usage, and totals."
method: GET
path: "/api/stats/overview"
tags: ["stats"]
---

# Returns the caller's usage overview: verdict breakdown, activity series, check usage, and totals.

`GET /api/stats/overview`

## Request

- Base URL: `https://api.pricklymails.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pricklymails.com/api/stats/overview`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Query parameters

- `granularity` string
- `days` integer

## Response `200`

Verdict breakdown, activity series, check usage, and totals.

- StatsOverviewResponse: JSON response body for `GET /api/stats/overview`.
  - `activity` ActivityPointResponse[], required: Zero-filled activity time series for the requested window.
    - `count` integer, required: Number of verifications recorded in this bucket.
    - `date` string, required: Start of the bucket, as an RFC3339 timestamp.
  - `activity_previous` ActivityPointResponse[], required: Zero-filled activity time series for the immediately preceding, equal-length window.
    - `count` integer, required: Number of verifications recorded in this bucket.
    - `date` string, required: Start of the bucket, as an RFC3339 timestamp.
  - `check_usage` CheckUsageResponse[], required: Per-check usage counts for the requested window.
    - `check` string, required: Check name (e.g. `"syntax"`, `"mx"`, `"smtp"`).
    - `count` integer, required: Number of verifications for which this check ran.
  - `recommendations` RecommendationBreakdownResponse, required: Per-recommendation-bucket counts in the response body: the 3-bucket "what to do with this address" grouping, orthogonal to the raw verdict breakdown above.
    - `remove` integer, required: Count of verifications recommended for removal from the list.
    - `review` integer, required: Count of verifications recommended for manual review.
    - `send` integer, required: Count of verifications recommended to send to.
  - `totals` StatsTotalsResponse, required: At-a-glance totals in the response body.
    - `avg_score` number, double, required: Average quality score (0-100) across the window's verifications.
    - `deliverable_pct` number, double, required: Percentage (0-100) of the window's verifications that resolved `valid`.
    - `verifications_in_range` integer, required: Number of verifications performed within the selected window.
  - `verdict_breakdown` VerdictBreakdownResponse, required: Per-status verdict counts in the response body.
    - `invalid` integer, required: Count of `invalid` verifications.
    - `risky` integer, required: Count of `risky` verifications.
    - `unknown` integer, required: Count of `unknown` verifications.
    - `valid` integer, required: Count of `valid` verifications.

## Other responses

- `401`: Missing or invalid API key, session token, or agent token.
- `403`: The key or agent token lacks the `usage:read` scope.

---

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