Usage

Two endpoints to see what your store has consumed and project what you'll need next month.

GET /v1/usage

Current calendar month, grouped by endpoint type.

Auth: platform key with usage:read.

Response 200

{
  "data": {
    "period": "2026-04",
    "tier":   "pro_plus",
    "usage": {
      "request": { "total": 31, "billable": 0 },
      "signup":  { "total": 3,  "billable": 2 },
      "event":   { "total": 0,  "billable": 0 },
      "webhook": { "total": 0,  "billable": 0 }
    },
    "limits": {
      "requests_per_month":  5000000,
      "signups_per_month":   50000,
      "webhooks_per_month":  500000,
      "requests_per_minute": 1200
    }
  }
}

Field reference

Field	Meaning
period	Always YYYY-MM. Resets on the 1st of each month at 00:00 UTC.
tier	Your current rate-limit tier.
usage.<group>.total	All requests in that group, including duplicates / rejections.
usage.<group>.billable	Only counted requests (e.g. duplicate signups don't bill).
limits	The effective limits — tier_limits overridden by any per-store override. -1 means unlimited.

Endpoint groups

Group	What counts
request	Every API call that authenticated successfully.
signup	Each /v1/signups call. Duplicates are counted in total but not billable.
event	Each /v1/events call.
webhook	Each outbound webhook delivery attempt (success or 4xx; 5xx retries each count).

GET /v1/usage/history

Hourly rollups over a date range — useful for charts and trend analysis.

Auth: platform key with usage:read.

Query parameters

Param	Type	Default	Notes
from	ISO date	7 days ago	Inclusive
to	ISO date	now	Exclusive

Range cap: 90 days.

Request

curl 'https://api.dzbuild.app/v1/usage/history?from=2026-04-01&to=2026-05-01' \
  -H "Authorization: Bearer $DZ_KEY"

Response 200

{
  "data": {
    "from": "2026-04-01T00:00:00+00:00",
    "to":   "2026-05-01T00:00:00+00:00",
    "rows": [
      { "period_hour": "2026-04-30 19:00:00", "endpoint_group": "request", "count": 26, "billable_count": 0 },
      { "period_hour": "2026-04-30 20:00:00", "endpoint_group": "request", "count": 5,  "billable_count": 0 },
      { "period_hour": "2026-04-30 20:00:00", "endpoint_group": "signup",  "count": 3,  "billable_count": 2 }
    ]
  }
}

Rows are returned in ascending period_hour order. Hours with zero usage in any group are omitted (sparse).

Plotting tips

• Daily aggregates: group rows by LEFT(period_hour, 10) (the date prefix).
• Stacked area: group by endpoint_group, then by hour for the X-axis.
• Quota burn rate: divide signup.billable_count cumulative by the elapsed fraction of the month, project to month-end.

A simple Python example:

import collections, datetime, requests, os

r = requests.get('https://api.dzbuild.app/v1/usage/history',
    params={'from': '2026-04-01', 'to': '2026-05-01'},
    headers={'Authorization': f"Bearer {os.environ['DZ_KEY']}"})
rows = r.json()['data']['rows']

by_day = collections.defaultdict(lambda: collections.Counter())
for row in rows:
    day = row['period_hour'][:10]
    by_day[day][row['endpoint_group']] += row['count']

for day, counts in sorted(by_day.items()):
    print(day, dict(counts))