# Rate limits

> Per-minute request limits for the Xholic API and MCP server by plan, in separate read, write and live X buckets.

Source: https://docs.xholic.ai/api/rate-limits/

Limits are per connection (each API key or connected app) and per minute, in three separate buckets so a script that reads a lot can never block posting.

| Bucket | Trial | Pro | Max | Ultra |
| --- | --- | --- | --- | --- |
| Reads (`read`) | 20 | 60 | 120 | 300 |
| Changes (`write`) | 5 | 20 | 40 | 100 |
| Live X lookups (`live_x`) | 5 | 15 | 30 | 60 |

Each action's bucket is listed in its reference entry. Unknown or lapsed plans get the trial limits.

- **Live X lookups** (25 actions, such as `search_x` and `get_person`) cost no credits but count toward your plan's existing X data limits. When those are used up, actions return stored data where they can, or `X_DATA_LIMIT_REACHED`.
- **Free tools without an account** (`/mcp/free`) share 10 requests per minute per IP address and their own daily budget, so they never eat into anyone's plan.
- A coarse per-address ceiling well above these numbers protects the service from floods.

## When you hit a limit

The response is `429` with `RATE_LIMITED`, a `Retry-After` header and `retryAfterSeconds` in the error. Every successful REST response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, so you can slow down before that.

Stored data (your posts, analytics, contacts, context and memory) is free to read within these limits.