Local prototype · simulated data

Usage API

Request counters for the calling key.

GET /v1/usage

Usage for the calling key in the current period

Local prototype · simulated data

Secret keys only.

Authentication

Authorization: Bearer <key> — a sk_test_… secret key from your server, or a pk_test_… publishable key from an allowed browser origin. See Authentication.

Responses

200 Usage counters. — Usage
401 Missing or invalid key. — Error
403 Key not allowed for this Origin or endpoint. — Error

Response fields (200)

Response fields
Field	Type	Required	Description
`data`	object	Yes
`data.key_prefix`	string	Yes
`data.period_start`	string	Yes	format date-time
`data.requests`	integer	Yes	min 0
`data.completed_addresses`	integer	No	Addresses returned by /v1/addresses/{id} for this key. The same address (id and unit) retrieved again with the same key within 24 hours counts once. Plans are counted in completed addresses. min 0
`data.billable_requests`	integer	Yes	Always 0 for test keys. min 0
`meta`	object	Yes
`meta.request_id`	string	Yes
`meta.source`	enum: "simulated", "live"	Yes	`simulated` for mock data. `live` is reserved and is never produced by this version.
`meta.billable`	boolean	Yes	Always `false` in this version.

Example

cURL

curl "http://localhost:8787/v1/usage" \
  -H "Authorization: Bearer sk_test_PLACEHOLDER"

JavaScript

// Server-side (Node 18+). Never ship a secret key to a browser.
const res = await fetch("http://localhost:8787/v1/usage", {
  headers: { Authorization: "Bearer sk_test_PLACEHOLDER" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.code);

Python

import requests

res = requests.get(
    "http://localhost:8787/v1/usage",
    headers={"Authorization": "Bearer sk_test_PLACEHOLDER"},
    timeout=10,
)
res.raise_for_status()
print(res.json())

Response 200 from the local prototype (simulated data):

JSON

{
  "data": {
    "key_prefix": "sk_test_PLAC",
    "period_start": "2026-10-25T00:00:00.000Z",
    "requests": 3,
    "billable_requests": 0,
    "completed_addresses": 1
  },
  "meta": {
    "request_id": "req_0000000000000000docs",
    "source": "simulated",
    "billable": false
  }
}