> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medlistiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits & plans

> Per-minute and monthly caps by plan, how enforcement works, what happens when you hit a limit.

Every API key is scoped to an 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

| Plan           | Monthly cap | Per-minute limit | Typical use                                               |
| -------------- | ----------- | ---------------- | --------------------------------------------------------- |
| **Free**       | 50 requests | 2 / min          | Evaluate the API end-to-end                               |
| **Starter**    | 500         | 60 / min         | Early-stage startup                                       |
| **Pro**        | 2,500       | 180 / min        | Growing past startup                                      |
| **Enterprise** | Custom      | Custom           | Email [brian@briankfung.com](mailto:brian@briankfung.com) |

Upgrade at any time from [Dashboard → Billing](https://medlistiq.com/dashboard/billing).

## When you hit the limit

Both caps return **HTTP 429** with a machine-readable detail:

<ResponseExample>
  ```json Rate limit exceeded theme={null}
  {
    "detail": {
      "error": "rate_limit_exceeded",
      "limit_per_minute": 60,
      "plan": "starter"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Monthly cap reached theme={null}
  {
    "detail": {
      "error": "monthly_cap_reached",
      "used": 500,
      "cap": 500,
      "plan": "starter",
      "upgrade_url": "https://medlistiq.com/dashboard/billing"
    }
  }
  ```
</ResponseExample>

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](https://medlistiq.com/dashboard/usage)
* **Programmatic** — drop us a note if you need an API for usage reporting; not
  built yet, prioritized by demand.

## 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.