Skip to content
CastPDF
Start free
Docs
API reference

Account

Test an API key and see its team and plan with GET /v1/me, read its mode with GET /v1/account and this month's usage with GET /v1/account/usage.

On this page

Three read-only endpoints tell you about the key you call with and the workspace behind it. GET /v1/me is the one to use as a connection test, for example when you paste a key into an automation tool. GET /v1/account/usage shows how many documents you used this month, so you can warn yourself before you reach a limit. None of them counts as a document, but each request counts against the key's rate limit like any other.

GET /v1/me

Who the key is: the team, its plan and what the plan allows, and the key's name. A wrong key gets invalid_api_key (401), so a 200 means the key works.

Request
curl https://api.castpdf.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
const res = await fetch('https://api.castpdf.com/v1/me', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
if (res.status === 401) throw new Error('The API key is not valid');
const me = await res.json();
console.log(me.team.name, me.plan.name, me.key.mode);
import requests

res = requests.get(
    "https://api.castpdf.com/v1/me",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
if res.status_code == 401:
    raise RuntimeError("The API key is not valid")
me = res.json()
print(me["team"]["name"], me["plan"]["name"], me["key"]["mode"])
200
{
  "team": { "id": "5e1b9c7a-2f4d-4a8b-9c0e-7d6f5a4b3c2d", "name": "Acme", "plan": "starter" },
  "plan": {
    "id": "starter",
    "name": "Starter",
    "docs_per_period": 2500,
    "rate_limit_per_min": 60,
    "webhooks": true,
    "batch_max_items": 500,
    "emails_per_day": 500
  },
  "key": { "id": "0f1e2d3c-4b5a-4968-8776-655443322110", "name": "Order system", "mode": "live", "prefix": "cpdf_live_0123" }
}
FieldDescription
teamobjectThe team's id, name and plan id.
planobjectThe plan's id and name, its documents a month (docs_per_period), the key's rate limit (rate_limit_per_min; test keys: 20), whether it includes webhooks, its items per batch (batch_max_items) and its emailed PDFs a day (emails_per_day).
keyobjectThe key's id, the name you gave it in the dashboard, its mode (live or test) and its prefix, the first 14 characters.

One key per integration, each with its own name, keeps them apart here and in the dashboard. The response has cache-control: no-store.

GET /v1/account

The team and key mode of the key you call with: a shorter answer than GET /v1/me.

curl
curl https://api.castpdf.com/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
200
{
  "team": { "id": "5e1b9c7a-2f4d-4a8b-9c0e-7d6f5a4b3c2d", "name": "Acme", "plan": "starter" },
  "key": { "mode": "live", "prefix": "cpdf_live_0123" }
}

GET /v1/account/usage

The team's live usage in the current monthly period. Test keys get the same numbers (test documents are never counted).

Request
curl https://api.castpdf.com/v1/account/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
const res = await fetch('https://api.castpdf.com/v1/account/usage', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const usage = await res.json();
console.log(`${usage.docs_used} of ${usage.docs_included} documents used`);
import requests

res = requests.get(
    "https://api.castpdf.com/v1/account/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
usage = res.json()
print(f"{usage['docs_used']} of {usage['docs_included']} documents used")
200
{
  "plan": "starter",
  "period_start": "2026-09-14T09:30:00.000Z",
  "period_end": "2026-10-14T09:30:00.000Z",
  "docs_used": 1250,
  "docs_included": 2900,
  "rollover_docs": 400,
  "overage_docs": 0,
  "overage_cost_cents": 0,
  "spending_cap_cents": 3800,
  "overage_blocked_reason": null,
  "prorated_upgrade": null
}
FieldDescription
planstringThe plan of the current period.
period_start, period_endstringThe monthly period, in UTC. Annual plans have monthly periods too.
docs_usedintegerSuccessful live documents in this period, included and overage together.
docs_includedintegerThe documents included in this period: the plan's monthly documents plus rollover_docs (after an upgrade during the period, a prorated amount).
rollover_docsintegerUnused documents carried over from the previous period (paid plans).
overage_docs, overage_cost_centsintegerDocuments beyond the included ones, and their cost so far in US cents.
spending_cap_centsinteger or nullThe cap on this period's overage cost, in US cents; null on the Free plan, which has no overage.
overage_blocked_reasonstring or nullnull when overage is available; otherwise why not: free, cancel_scheduled, past_due, no_subscription, currency_unsupported, overage_unpaid or billed_this_period.
prorated_upgradeobject or nullAfter an upgrade during the period, { "plan_docs", "upgraded_at" }: the plan's full monthly documents (which apply from period_end) and when you upgraded, which explain why docs_included is lower this period. Otherwise null.

See Usage and billing for how these numbers work, and what happens at the limit.

Updated Something unclear? [email protected], a real person replies.