Rate Limits
All API requests are rate-limited based on your subscription plan. Limits are applied per API key.
Plan limits
| Product | Plan | Requests per Minute | Monthly Quota |
|---|---|---|---|
| Advanced Chart | Monthly | 120 RPM | 100,000 units |
| Advanced Chart | 3-Month | 120 RPM | 150,000 units |
| Advanced Chart | Annual | 120 RPM | 300,000 units |
| Advanced Chart | Lifetime | 120 RPM | 150,000 units |
| SAGE API | Monthly | 100 RPM | 100,000 units |
| SAGE API | 3-Month | 100 RPM | 150,000 units |
| SAGE API | Annual | 100 RPM | 300,000 units |
| SAGE API | Lifetime | 100 RPM | 150,000 units |
Advanced Chart and SAGE API are separate plans with separate keys. Rate limits and unit consumption are tracked independently per key.
What counts as a unit?
Most endpoints consume 1 unit per request. Transit endpoints and SAGE queries consume more:
| Endpoint Type | Unit Cost |
|---|---|
Chart endpoints (/api/chart, /api/composite, /api/astrology) | 1 unit |
Multi-chart batch (/api/multi-chart) | 1 unit per chart in batch |
Planetary returns (/api/returns) | 1 unit per request |
| Transit endpoints (daily granularity) | 1 unit per day in range |
| Transit endpoints (hourly granularity) | 24 units per day in range |
| Transit endpoints (minute granularity) | 1,440 units per day in range |
Transit periods (/api/transits/periods) | 1 unit per request |
Retrograde periods (/api/retrogrades) | 1 unit per request |
SAGE query (/api/sage) | 5 units per query |
MCP tool calls (/mcp) | Same as equivalent REST endpoint |
Failed requests (4xx/5xx responses) are not counted against your quota.
Rate limit headers
Every API response includes rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per minute |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
X-Monthly-Units-Used | Units consumed this billing period |
X-Monthly-Units-Limit | Total units available this billing period |
Exceeding limits
When you exceed the rate limit, you'll receive a 429 Too Many Requests response:
{
"success": false,
"error": "Rate limit exceeded. Try again in 60 seconds."
}
When your monthly quota is exhausted:
{
"success": false,
"error": "Monthly usage limit reached. Upgrade your plan or wait for the next billing period."
}