api reference

Usage and health

GET /v1/usage returns your own quota and usage; GET /v1/health reports API status; /openapi.json is the machine-readable spec.

View as Markdown

GET /v1/usage

GET https://api.isbusinessemail.com/v1/usage

Returns usage for the account that owns the key. Secret keys only. Reading usage doesn’t count as a check.

curl -s https://api.isbusinessemail.com/v1/usage \
  -H "Authorization: Bearer $IBE_API_KEY"

The response includes:

  • your tier and its limits in limits: quota_period is day on the free tier and month on a paid plan; per_day or per_month holds the quota and the other one is null; overage_billed is true when checks past the quota keep working and are billed (paid plans)
  • the current quota window in period: start, end, checks used, the limit, what’s remaining, overage (checks past the included ones on a paid plan) and when it resets_at (00:00 UTC on the free tier, the start of your next billing month on a paid plan)
  • today: checks used today, remaining (what can still be used: the day’s quota on the free tier, the month’s on a paid plan) and resets_at (the next 00:00 UTC)
  • your last 30 days in daily, broken down by category

For a free account it looks like this (trimmed):

{
  "tier": 0,
  "limits": {
    "per_second": 5,
    "per_day": 100,
    "per_month": null,
    "quota_period": "day",
    "overage_billed": false,
    "deep_per_day": 1000,
    "batch_max": 100,
    "batch_per_second": 1
  },
  "period": {
    "period": "day",
    "start": "2026-10-21T00:00:00.000Z",
    "end": "2026-10-22T00:00:00.000Z",
    "used": 37,
    "limit": 100,
    "remaining": 63,
    "overage": 0,
    "resets_at": "2026-10-22T00:00:00.000Z"
  },
  "today": { "used": 37, "remaining": 63, "resets_at": "2026-10-22T00:00:00.000Z" },
  "daily": []
}

The exact field names are in /openapi.json and the API reference. For history (30-day charts, latency percentiles, your last 1,000 requests by domain), use the dashboard.

You often don’t need this endpoint: every /v1/check response already carries X-RateLimit-Remaining and the RateLimit header. See Rate limits.

Example: alert before you run out

import os
import requests

r = requests.get(
    "https://api.isbusinessemail.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['IBE_API_KEY']}"},
    timeout=3,
)
r.raise_for_status()
print(r.json())  # feed the remaining-checks value into your monitoring

GET /v1/health

GET https://api.isbusinessemail.com/v1/health

A cheap liveness check for your monitoring. No key needed, not counted. A 200 means the API is up. During partial outages checks keep working from our lists; individual check responses then carry degraded: true.

Status history and incidents: status.isbusinessemail.com.

GET /openapi.json

GET https://api.isbusinessemail.com/openapi.json

The OpenAPI 3.1 description of the public API, generated from the same schemas that validate requests and responses. Use it to generate a client, import into Postman or Insomnia, or browse it in the API reference.