Skip to content
HookDeploy
On this page ↓

Usage API

Retrieve current month usage and plan limits for your organization.

The Usage API returns your organization’s current month usage counters alongside your plan limits — useful for building dashboards, usage alerts, or automated upgrade prompts.

Agent allowances are not included. Production agent counts, max_agents, and agent overage are available in the HookDeploy dashboard only (check_agent_limit RPC). This endpoint intentionally covers requests, storage, endpoints, members, and forward-destination counts — not agents.

Get usage

GET /v1/usage

Returns usage for the current calendar month and the limits for your current plan.

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

Response:

{
  "data": {
    "data": {
      "plan": "starter",
      "billing_interval": "monthly",
      "requests_this_month": 1250,
      "max_requests_per_month": 25000,
      "storage_bytes": 19251,
      "max_storage_bytes": 5368709120,
      "endpoint_count": 8,
      "max_endpoints": 25,
      "member_count": 2,
      "max_users": 2,
      "destination_count": 3,
      "max_forward_destinations": 5,
      "custom_response": false,
      "response_delay": false
    }
  }
}

Fields:

FieldDescription
planYour current plan key: free, starter, pro, or scale
billing_intervalmonthly or yearly. Usage always resets monthly regardless of billing interval.
requests_this_monthWebhook requests captured this calendar month
max_requests_per_monthMetered monthly request capacity for your plan. -1 means unlimited. This counter is not itself a hard ingestion gate.
storage_bytesTotal payload storage used this month in bytes
max_storage_bytesMonthly storage limit in bytes. -1 means unlimited.
endpoint_countNumber of endpoints in your organization
max_endpointsEndpoint limit for your plan. -1 means unlimited.
member_countNumber of active members in your organization
max_usersMember limit for your plan. -1 means unlimited.
destination_countNumber of enabled forward destinations across all endpoints
max_forward_destinationsForward destination limit per endpoint for your plan. -1 means unlimited.
custom_responseWhether your plan includes custom response configuration
response_delayWhether your plan includes response delay

requests_this_month counts requests in your current usage cycle: the calendar month (UTC) on the Free plan, and the current billing cycle on paid plans, starting from your renewal date. Annual plans use monthly cycles. The billing_interval field shows whether you pay monthly or yearly.

Plan limits: A value of -1 for any limit means the field is unlimited on your plan.

Example: check if near request limit

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

CURRENT=$(echo $USAGE | jq '.data.data.requests_this_month')
MAX=$(echo $USAGE | jq '.data.data.max_requests_per_month')

echo "Used $CURRENT of $MAX requests this month"

Next steps