Skip to main content
Every API key is scoped to a Clerk organization, and every organization is on a plan. Plans gate two dimensions:
  • Per-minute rate limit — sliding window, counted per API key
  • Monthly request cap — counted per org, resets on the 1st of each calendar month (UTC)

​
Plan matrix

PlanMonthly capPer-minute limitTypical use
Free100 requests10 / minBuild and test your integration
Starter10,00060 / minSmall production app
Pro100,000300 / minReal production traffic
EnterpriseCustomCustomEmail support@medresolve
Upgrade at any time from Dashboard → Billing.

​
When you hit the limit

Both caps return HTTP 429 with a machine-readable detail: 
{
  "detail": {
    "error": "rate_limit_exceeded",
    "limit_per_minute": 60,
    "plan": "starter"
  }
}

{
  "detail": {
    "error": "monthly_cap_reached",
    "used": 10000,
    "cap": 10000,
    "plan": "starter",
    "upgrade_url": "https://medlistiq.com/dashboard/billing"
  }
}
Rate-limit responses also carry a Retry-After header with the number of seconds until the oldest in-window request ages out. Respect it.

​
How enforcement works

  • Rate limit is enforced per container (we run on Cloud Run). The effective global limit is your plan limit × number of concurrent containers. For stricter guarantees reach out — we can move to a Redis-backed limiter.
  • Monthly cap is enforced per org and cached 60s. You may slightly overshoot during that cache window, but only by a handful of requests. We honor the cap strictly once the cache refreshes.
  • Only 2xx responses count against your cap. Failed auth, rate-limit rejects, and validation errors don’t consume quota.
  • Demo/anonymous requests don’t count (when key auth is disabled in dev — not applicable to production).

​
Monitoring your usage

  • Portal dashboard — real-time “X of Y used this month” progress bar at Dashboard → Usage
  • Admin API — GET /admin/plan and GET /admin/usage are Clerk-authenticated endpoints consumed by the portal; you can hit them from your own infra if you need to script usage reporting

​
Monthly reset

Caps reset at midnight UTC on the 1st of each calendar month. We use calendar-month windows, not billing-cycle windows — industry standard, matches what Stripe, OpenAI, and Anthropic do. If your billing cycle starts mid-month, you still get your full cap from day 1 of your first month.