pricklymails-com Stats API
Your usage statistics, and the public service figures.
Operations 2
GET
/api/stats/overview
Returns the caller's usage overview: verdict breakdown, activity series, check…
#
Your usage statistics, and the public service figures.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pricklymails-com:pricklymails-com-stats-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Pricklymails Com Stats API
version: 0.9.0
contact:
email: support@pricklymails.com
license:
name: Proprietary
description: 'Operations tagged stats across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Stats
description: Your usage statistics, and the public service figures.
paths:
/api/stats/overview:
get:
tags:
- Stats
summary: 'Returns the caller''s usage overview: verdict breakdown, activity series, check…'
description: Accepts optional `granularity` (`"hour"` | `"day"` | `"week"` | `"month"`, default `"day"`) and `days` (the window length, default 28, clamped to 1..=364) query params. Authenticated with a dashboard session, or an API key or agent token holding the `usage:read` scope.
operationId: get_stats_overview
parameters:
- name: granularity
in: query
description: 'Bucket width for the activity time series: `hour`, `day`, `week`, or `month` (default `day`).'
required: false
schema:
type: string
- name: days
in: query
description: 'Number of whole buckets the activity window covers at the chosen granularity, ending with the current, still-open bucket (default 28, clamped to 1..=364): 8 at `day` gives 8 buckets, 1 at `hour` gives 24, 364 at `month` gives 12.'
required: false
schema:
type: integer
format: int32
minimum: 0
responses:
'200':
description: Verdict breakdown, activity series, check usage, and totals.
content:
application/json:
schema:
$ref: '#/components/schemas/StatsOverviewResponse'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `usage:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/stats/summary:
get:
tags:
- Stats
summary: Returns the public service figures
description: 'Public and unauthenticated: the all-time total verification count, the average check latency, and its 90th-percentile latency, refreshed at most once every 24 hours.'
operationId: get_public_stats
responses:
'200':
description: All-time public verification stats.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicStatsResponse'
components:
schemas:
StatsOverviewResponse:
type: object
description: JSON response body for `GET /api/stats/overview`.
required:
- verdict_breakdown
- recommendations
- activity
- activity_previous
- check_usage
- totals
properties:
activity:
type: array
items:
$ref: '#/components/schemas/ActivityPointResponse'
description: Zero-filled activity time series for the requested window.
activity_previous:
type: array
items:
$ref: '#/components/schemas/ActivityPointResponse'
description: Zero-filled activity time series for the immediately preceding, equal-length window.
check_usage:
type: array
items:
$ref: '#/components/schemas/CheckUsageResponse'
description: Per-check usage counts for the requested window.
recommendations:
$ref: '#/components/schemas/RecommendationBreakdownResponse'
description: Per-recommendation-bucket counts for the requested window.
totals:
$ref: '#/components/schemas/StatsTotalsResponse'
description: At-a-glance totals for the requested window.
verdict_breakdown:
$ref: '#/components/schemas/VerdictBreakdownResponse'
description: Per-status verdict counts for the requested window.
CheckUsageResponse:
type: object
description: A single check-usage count in the response body.
required:
- check
- count
properties:
check:
type: string
description: Check name (e.g. `"syntax"`, `"mx"`, `"smtp"`).
count:
type: integer
format: int32
description: Number of verifications for which this check ran.
minimum: 0
ApiErrorBody:
type: object
description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
required:
- error
properties:
error:
$ref: '#/components/schemas/ApiErrorDetail'
description: Error detail.
RecommendationBreakdownResponse:
type: object
description: '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.
Supports an honest "sendable" rate (`send / (remove + send + review)`), since the raw verdict breakdown still lumps
catch-all and role-based addresses into `risky` despite normally being worth sending to.'
required:
- remove
- send
- review
properties:
remove:
type: integer
format: int32
description: Count of verifications recommended for removal from the list.
minimum: 0
review:
type: integer
format: int32
description: Count of verifications recommended for manual review.
minimum: 0
send:
type: integer
format: int32
description: Count of verifications recommended to send to.
minimum: 0
StatsTotalsResponse:
type: object
description: At-a-glance totals in the response body.
required:
- verifications_in_range
- avg_score
- deliverable_pct
properties:
avg_score:
type: number
format: double
description: Average quality score (0-100) across the window's verifications.
deliverable_pct:
type: number
format: double
description: Percentage (0-100) of the window's verifications that resolved `valid`.
verifications_in_range:
type: integer
format: int32
description: Number of verifications performed within the selected window.
minimum: 0
ActivityPointResponse:
type: object
description: A single time-bucketed activity point in the response body.
required:
- date
- count
properties:
count:
type: integer
format: int32
description: Number of verifications recorded in this bucket.
minimum: 0
date:
type: string
description: 'Start of the bucket, as an RFC3339 timestamp.
Carrying the full timestamp (rather than a date-only string) preserves the hour for the `"hour"` granularity,
where a date-only string would collapse every bucket in a day to the same value.'
ApiErrorDetail:
type: object
description: Detail of an error response.
required:
- code
properties:
code:
type: string
description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
message:
type:
- string
- 'null'
description: 'Present on most error kinds and equal to `code`; the API returns no localized text.
Absent for error kinds that carry no extra detail.'
VerdictBreakdownResponse:
type: object
description: Per-status verdict counts in the response body.
required:
- valid
- risky
- invalid
- unknown
properties:
invalid:
type: integer
format: int32
description: Count of `invalid` verifications.
minimum: 0
risky:
type: integer
format: int32
description: Count of `risky` verifications.
minimum: 0
unknown:
type: integer
format: int32
description: Count of `unknown` verifications.
minimum: 0
valid:
type: integer
format: int32
description: Count of `valid` verifications.
minimum: 0
PublicStatsResponse:
type: object
description: JSON response body for `GET /api/stats/summary`.
required:
- total_verifications
properties:
avg_latency_ms:
type:
- integer
- 'null'
format: int64
description: 'Average recorded check duration in milliseconds, rounded to the nearest millisecond.
`null` when no verification has recorded a duration yet.'
p90_latency_ms:
type:
- integer
- 'null'
format: int64
description: '90th-percentile recorded check duration in milliseconds: an actual observed duration at or under which at
least 90% of results land. `null` when no verification has recorded a duration yet.'
total_verifications:
type: integer
format: int64
description: All-time total number of verification results recorded, across every customer.
securitySchemes:
bearer_api_key:
type: http
scheme: bearer
description: A `pm_live_*` or `pm_test_*` API key.
jwt:
type: http
scheme: bearer
description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml