Usage API | HookDeploy

The Usage API returns current consumption and plan limits for the authenticated organization.

Get usage

GET /v1/usage

curl -s "https://api.hookdeploy.dev/v1/usage" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Response:

{
  "data": {
    "requests_this_month": 42,
    "endpoint_count": 3,
    "member_count": 2,
    "limits": {
      "max_endpoints": "5",
      "max_users": "1",
      "max_requests_per_month": "500",
      "max_payload_bytes": "262144",
      "retention_days": "7"
    }
  }
}

Response fields

Current usage

Field	Description
`requests_this_month`	Webhooks captured this calendar month across all endpoints
`endpoint_count`	Active endpoints in the organization
`member_count`	Organization members (including owner)

Limits

All limit values are strings. -1 means unlimited.

Field	Description
`max_endpoints`	Maximum endpoints allowed
`max_users`	Maximum team members
`max_requests_per_month`	Monthly webhook ingestion quota
`max_payload_bytes`	Maximum request body size in bytes
`retention_days`	Days before captured requests are deleted

Plan limit reference

Plan	max_users	max_endpoints	max_requests_per_month	max_payload_bytes	retention_days
Free	1	5	500	262144 (256 KB)	7
Starter	2	25	25000	1048576 (1 MB)	30
Team	-1	50	500000	26214400 (25 MB)	90
Enterprise	-1	-1	-1	104857600 (100 MB)	365

Using usage data

Before creating an endpoint — check if you’re at the limit:

USAGE=$(curl -s "https://api.hookdeploy.dev/v1/usage" \
  -H "Authorization: Bearer hd_live_YOUR_KEY")

ENDPOINTS=$(echo $USAGE | jq -r '.data.endpoint_count')
MAX=$(echo $USAGE | jq -r '.data.limits.max_endpoints')

echo "Using $ENDPOINTS of $MAX endpoints"

Monitoring ingestion — poll usage in CI or cron jobs to alert before hitting monthly limits:

REQUESTS=$(curl -s "https://api.hookdeploy.dev/v1/usage" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  | jq -r '.data.requests_this_month')

LIMIT=$(curl -s "https://api.hookdeploy.dev/v1/usage" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  | jq -r '.data.limits.max_requests_per_month')

if [ "$REQUESTS" -ge "$LIMIT" ]; then
  echo "Monthly request limit reached"
fi

What counts toward limits

Action	Counts as request?	Counts as endpoint?
Incoming webhook to `hookdeploy.dev/h/*`	Yes	—
API replay	No	—
Auto-forward	No (same ingestion event)	—
API health check	No	—
Create endpoint via API/dashboard	—	Yes

Usage counters reset at the start of each calendar month (UTC).

When limits are exceeded

Max endpoints — POST /v1/endpoints returns 429 plan_limit
Max requests/month — Incoming webhooks return 429 with {"error":"plan limit reached"}
Max payload — Incoming webhooks return 413 Payload Too Large
Max users — Invitations fail in the dashboard (not via this API)

No overage charges on self-serve plans. Upgrade via the dashboard Billing page.

Next steps

Plans — Full plan comparison
Requests concept — Retention and payload details
Endpoints API — Create endpoints within your limit