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

# Rate limits

> How Atlas API limits affect public reads, API keys, discovery, and workspace integrations.

## Overview

Rate limits protect Atlas from noisy clients while keeping public civic data
available. The important design choice is not just “how many requests can I
send?” It is “what access pattern matches the workflow?”

## Choose the right access pattern

| Workflow                   | Recommended access                                          |
| -------------------------- | ----------------------------------------------------------- |
| Occasional public lookup   | Public unauthenticated API                                  |
| Scheduled script or export | API key                                                     |
| Team workflow automation   | API key scoped to the workspace                             |
| AI assistant or MCP client | OAuth through the MCP client                                |
| High-volume crawling       | Do not crawl blindly; use focused queries and cache results |

Unauthenticated requests always use the public limit even if the user also has a
paid account. Authenticate recurring integrations.

## Current limits

| Access pattern                             | Limit                                                                     |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| Public unauthenticated API                 | 30 reads/minute, 10 writes/minute, and 120 total requests/hour per client |
| Credential headers before verification     | 60 requests/minute and 600 total requests/hour per client                 |
| Pro API key                                | 1,000 requests per day per key                                            |
| Team or Research Pass API key              | 10,000 requests per day per key                                           |
| Free research runs                         | 2 runs per month                                                          |
| Pro, Team, and Research Pass research runs | Unlimited                                                                 |

Use the generated reference and [pricing page](/docs/account/pricing) for exact plan
details when limits change.

An `Authorization` or `X-API-Key` header only receives authenticated limits
after Atlas verifies it. Invalid or forged credential headers are treated as
anonymous traffic after the pre-auth protection bucket.

## Build with limits in mind

* Cache place, taxonomy, and source responses when the source data does not need to be live.
* Page through results deliberately instead of requesting every record.
* Preserve entity ids and source ids so you can refresh specific records later.
* Use coverage endpoints to decide where more API calls are worth spending.
* Back off on `429` instead of retrying in a tight loop.

## Handling 429

A rate-limited response means the request was understood but the client has
exhausted its current window.

When that happens:

1. Stop the current loop.
2. Check rate-limit headers when present.
3. Use `Retry-After` or wait until `X-RateLimit-Reset` when present.
4. Cache the successful responses you already received.
5. Authenticate or upgrade only if the workflow truly needs higher volume.

## When to redesign instead of upgrade

Higher limits are not a substitute for a better workflow. Redesign the
integration if it repeatedly:

* Refetches the same actors without using ids.
* Drops sources and has to rediscover evidence.
* Crawls all places to answer one local question.
* Starts discovery runs without a review plan.
* Polls completed runs forever.

## Next steps

<CardGroup cols={2}>
  <Card title="API quickstart" icon="rocket" href="/docs/api/quickstart">
    Make a focused public API request.
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api/authentication">
    Use API keys or OAuth for recurring workflows.
  </Card>

  <Card title="Plans & pricing" icon="credit-card" href="/docs/account/pricing">
    Compare limits by plan before redesigning an integration.
  </Card>

  <Card title="API reference" icon="code" href="/docs/api/reference">
    Check exact response headers and endpoint requirements.
  </Card>
</CardGroup>