Account Metrics & Usage

GET /account/v{N}/metrics returns the current usage and quota for the API key you pass. Replace {N} with the API version your key is on (v10–v60). Use it to show an in-app dashboard, set up alerting before you run out of quota, or debug an unexpected 108 by confirming your plan limits.

Making the call

Pass your API key as a query parameter (or as X-API-Key header) to GET /account/v{N}/metrics (examples below use v60):

$
curl "https://api.zip-tax.com/account/v60/metrics?key=YOUR_API_KEY"

Response shape (v60)

1
{
2
  "request_count": 4215,
3
  "request_limit": 100000,
4
  "usage_percent": 4.215,
5
  "is_active": true,
6
  "message": "Contact support@zip.tax to modify your account"
7
}

Legacy response (v10–v50)

Older API versions split the counters into core_* (tax lookups) and geo_* (geocoded lookups). All new keys use the v60 shape. If you’re still on a legacy key, you’ll see:

1
{
2
  "is_active": true,
3
  "core_request_count": 4215,
4
  "core_request_limit": 100000,
5
  "geo_request_count": 4215,
6
  "geo_request_limit": 100000,
7
  "geo_enabled": true,
8
  "core_usage_percent": 4.215,
9
  "geo_usage_percent": 4.215,
10
  "message": "Contact support@zip.tax to modify your account"
11
}

Patterns

Show a usage widget in your dashboard

Poll once when the page loads, not on every render:

1
async function loadUsageWidget() {
2
  const res = await fetch(
3
    "https://api.zip-tax.com/account/v60/metrics",
4
    { headers: { "X-API-Key": process.env.ZIPTAX_KEY } }
5
  );
6
  const { request_count, request_limit, usage_percent } = await res.json();
7
8
  document.querySelector("#used").textContent = request_count.toLocaleString();
9
  document.querySelector("#limit").textContent = request_limit.toLocaleString();
10
  document.querySelector("#bar").style.width = `${usage_percent}%`;
11
}

Alert before you run out

Check metrics on a schedule (hourly or daily is plenty) and page your team when you cross a threshold:

1
def check_quota():
2
    res = requests.get(
3
        "https://api.zip-tax.com/account/v60/metrics",
4
        headers={"X-API-Key": os.environ["ZIPTAX_KEY"]},
5
    )
6
    m = res.json()
7
8
    if m["usage_percent"] >= 80:
9
        page_team(f"Ziptax usage at {m['usage_percent']:.0f}%")
10
    if not m["is_active"]:
11
        page_team("Ziptax key is deactivated")

Debug an unexpected 108

If you’re getting 108s but your plan shouldn’t hit the rate limit, /account/v{N}/metrics can confirm your key is active and reachable. Remember: 108s come from the per-minute request_rate, not from request_limit, so a low usage_percent here doesn’t rule out a 108. Check the X-RateLimit-Limit header on the 108 response instead.

Authentication and errors

The /account/v{N}/metrics endpoint uses the same API key auth as /request/v*: either X-API-Key header or key= query parameter. If the key is missing, you’ll get an HTTP 400 with a short error body:

1
{
2
  "error": "API key is required as a query parameter",
3
  "message": "The parameter 'key' is required"
4
}

If the key is valid but not found in Ziptax’s account database, the response is still HTTP 200 with zeros across the board and is_active: false. Check is_active before trusting the numbers.

Related