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

# Keys and limits

> How a key is sent, what a team's plan allows a day, and what to do when a call is refused for a limit.

## Sending a key

1. Someone on a team whose plan includes the API makes a key in the workspace, under Settings › API keys. It's shown once.
2. Keep it in the environment, as `PODDATA_API_KEY`. Never print it or write it to a file.
3. Send it on every call, in the `Authorization` header:

   ```bash theme={null}
   curl -s https://api.poddata.ai/v1/usage -H "Authorization: Bearer $PODDATA_API_KEY"
   ```

A production key starts `pd_live_` and works only on `api.poddata.ai`. A staging key starts `pd_test_` and works only on staging. A key belongs to its team: everything it reads and writes is that team's, and nothing it gets says what another team looks at.

## What a plan allows

| | Free | Pro | Pilot | Enterprise |
| - | - | - | - | - |
| The API and the MCP server | No | Yes | Yes | Yes |
| API keys a team holds at once | 0 | 1 | 1 | No limit |
| Reads of a target asked for now, a UTC day | 1 | 10 | 10 | No limit |
| Rival finds, a UTC day | 1 | 3 | 3 | No limit |
| Runs of PodData's agent a key or an assistant starts, a UTC day | 0 | 3 | 3 | 10 |
| SEC filers brought in by request, a UTC day | 1 | 5 | 5 | 25 |
| Person lookups that found someone, a month | 3 | 20 | 20 | No limit |
| Sources queued for a person, a UTC day | 1 | 10 | 10 | No limit |
| Active trackers | 1 | 100 | 100 | No limit |
| Lists, and people and companies on each | 1, 25 | 25, 500 | 25, 500 | No limit, No limit |
| Webhooks | No | Yes | Yes | Yes |
| Connections to your team's own data vendors (by request today) | No | Yes | Yes | Yes |
| Quotes the API answers, a month (counted, not held to it) | 0 | 50,000 | 50,000 | No limit |
| Documents read whole, a month (counted, not held to it) | 0 | 1,000 | 1,000 | No limit |

Every key, on every plan with the API: 120 requests a minute, then a `429` with `Retry-After`; 50 documents, transcripts and recordings read whole a UTC day; 20 quotes from one episode a UTC day.

"A UTC day" starts at midnight UTC. A plan's count is the team's, whatever key or person asked. The last three limits are each key's own, and an assistant signed in as a person is held to them as a key is.

## When a call is refused for a limit

| You get | It means | Do this |
| - | - | - |
| `429`, code `slow_down`, with `Retry-After` | More than the key's requests a minute | Wait the seconds `Retry-After` gives, then carry on where you were |
| `429` on starting a run of PodData's agent | The team's runs a UTC day are used up | `Retry-After` counts down to midnight UTC. Tell the person; write the report yourself meanwhile |
| `403`, code `plan` | A plan's limit a day is used up, or the plan doesn't include this | Read the message: it says the limit and when it opens again. Tell the person, and carry on with what doesn't need it |
| Fewer quotes from one episode than you asked for, or `429` for one asked for by id | The key has had 20 different quotes from that episode today, so a list leaves out the rest | Cite the quotes you have; the rest open at midnight UTC, which `Retry-After` counts down to |

An ask PodData has taken already and not yet acted on, such as a read of a target that no source has run on yet, is answered again with `again: true` and isn't counted twice.

## What's counted

Every call with a key is counted, refused ones too. `GET /usage` gives the team's counts by day and kind:

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/usage?from=2026-11-01' -H "Authorization: Bearer $PODDATA_API_KEY"
```

```json theme={null}
{ "data": [{ "day": "2026-11-14", "kind": "api", "count": 412 }] }
```

The MCP tool `get_usage` gives the same.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.