Track API quota and billing-cycle consumption

Goal

Understand how many validations you have consumed in the current billing cycle, where you are relative to your plan's monthly limit, which operations account for most of the usage, and how usage patterns have shifted over time. Use these signals to plan scale-up events and to build usage alerts in your own monitoring stack.

Prerequisites

• An active API key (veriko_…). No additional permission beyond authentication is required for the usage endpoints.

Steps

1. Check the current-cycle quota snapshot

GET /v1/usage/summary returns your plan's monthly limit, validations consumed, validations remaining, and a pre-classified tone indicator (ok, warn, danger).

curl 'https://api.veriko.mx/v1/usage/summary' \
  -H 'Authorization: Bearer veriko_••••'

{
  "data": {
    "type": "usage_summary",
    "attributes": {
      "limit": 5000,
      "used": 2100,
      "remaining": 2900,
      "used_percent": 42.0,
      "tone": "ok",
      "resets_at": "2025-05-01T00:00:00Z",
      "quota_kind": "cycle",
      "renews": true
    }
  }
}

Tone thresholds:

quota_kind and renews. An account that has not yet claimed the free plan draws, while it lasts, on a trial quota separate from the subscription cycle: quota_kind: "trial" marks that, and renews: false means resets_at marks the end of a technical period, not a promise of a top-up — once the trial runs out, no more units arrive until the plan is claimed. With quota_kind: "cycle" (the usual case) renews is true: the billing cycle does replenish the quota. Both fields are additive — a client that ignores them keeps working the same way — and they also appear in meta.quota from GET /v1/billing/subscription.

If the trial quota runs out, any validating endpoint responds 429 with meta.plan_unclaimed: true: it is not a limit resetting on its own, it is an account that has not claimed its plan yet and therefore has nothing left to consume.

2. Get raw API usage counters

GET /v1/api/usage provides a broader snapshot including requests today, requests this month, plan quota, and the current Banxico service status.

curl 'https://api.veriko.mx/v1/api/usage' \
  -H 'Authorization: Bearer veriko_••••'

{
  "data": {
    "type": "api_usage",
    "attributes": {
      "requests_today": 42,
      "requests_month": 580,
      "quota": {
        "plan_slug": "basic",
        "limit": 1000,
        "used": 420,
        "remaining": 580,
        "resets_at": "2025-04-01T00:00:00Z"
      }
    }
  }
}

3. Check rate-limit caps

The plan enforces per-minute limits in addition to the monthly quota: requests per key on the API and webhook deliveries per destination host. Check configured limits with:

curl 'https://api.veriko.mx/v1/usage/limits' \
  -H 'Authorization: Bearer veriko_••••'

The response returns rate_limits.api.key_per_minute and rate_limits.webhooks.host_per_minute, which the plan sets, together with the per-IP ceiling and the global per-host cap, separately from the monthly quota count. The consumption of the current window is reported by the X-RateLimit-* headers on every API response (rate limits).

4. Inspect per-operation breakdown

See which endpoints are consuming the most quota in the current cycle:

curl 'https://api.veriko.mx/v1/usage/breakdown' \
  -H 'Authorization: Bearer veriko_••••'

5. View historical usage trends

GET /v1/usage/history returns time-bucketed usage data. Combine with the insights trends endpoint for richer time-series analysis.

curl 'https://api.veriko.mx/v1/usage/history' \
  -H 'Authorization: Bearer veriko_••••'

6. View the usage heatmap

GET /v1/usage/heatmap shows activity density by hour of day and day of week — useful for understanding peak usage windows.

curl 'https://api.veriko.mx/v1/usage/heatmap' \
  -H 'Authorization: Bearer veriko_••••'

7. Export usage data

Download raw usage data as CSV or XLSX for ingestion into your analytics pipeline:

curl 'https://api.veriko.mx/v1/api/usage/export?format=csv' \
  -H 'Authorization: Bearer veriko_••••' \
  --output usage-export.csv

What's next

• Analyze validation success rates and counterparty trends: see Analyze insights.
• Generate finance and reconciliation reports: see Generate finance reports.