# API

as_of: 2026-10-20

Read-only, free, no account. Base URL `https://parrot.markets/api/v1`. Full reference: [/docs](/docs) and [/openapi.json](/openapi.json). For MCP, see [Agents](/agents).

## Quick start

```
curl "https://parrot.markets/api/v1/upcoming?category=earnings&days=7"
curl "https://parrot.markets/api/v1/word?entity=nvidia&word=Taiwan"
```

## One call per question

| Question | Call | Size |
|---|---|---|
| What is coming up? | `upcoming?category=fed&days=7` | ≤2.8 KB per category-week |
| Who is this speaker? | `entity?id=donald-trump` | ≤1.6 KB |
| Everything about one event | `brief?event=<id>` | ≤3.2 KB a page (`offset=` pages the rest) |
| Will they say this word? | `word?entity=<id>&word=Tariff` | ≤480 bytes, one line |
| Where was it said? | `quotes?entity=<id>&word=Tariff` | ~250 bytes per quote |
| Play the moment | `clips?entity=<id>&word=Tariff` | ~200 bytes per clip |
| Who talks about X? | `search?q=tariff` | ~300 bytes per hit |
| What changed? | `changes?since=<as_of>` | ≤4 KB per 50 changes |

Sizes are bytes of the default TSV answer. A "≤" size is a budget our tests enforce; "~" is typical. Earnings calls also take `symbol=NFLX` in place of `entity=`.

## Formats

`format=tsv` (default for tables), `json` (columnar: `{"cols":[...],"rows":[[...]]}`) or `md`. The column header is sent once per response.

## Columns

| Column | Meaning |
|---|---|
| `w` | the word as listed |
| `key` | normalised word key |
| `thr` | count threshold ("3+ times" is 3) |
| `scope` | who counts (see [Methodology](/methodology#who-counts)) |
| `n`, `y` | settled markets on this word, and how many settled YES |
| `l10`, `streak`, `last_y` | last 10 results, current streak, date of the last YES |
| `tn`, `th` | transcript history: appearances with a hit, out of the last N |
| `p`, `p_src` | displayed probability and the model behind it, where published |
| `cnt`, `cnt_all` | count under the market's scope, and for all speakers |
| `res` | result |
| `t` | first hit, seconds into the source |
| `clip` | `yt:<video id>@<start>-<end>`, or `mp3:<source>@<start>-<end>` for the publisher's audio |
| `px` | price, only with `markets=1` |

Every response carries `as_of` and, where it applies, `src` and `text_kind`. Icons appear only with `fields=full`.

## Caching

Responses send an `ETag`. Send it back in `If-None-Match` and you get `304` with no body while nothing has changed. Poll `changes?since=` instead of re-pulling lists.

## Limits

| Who | Normal endpoints | Heavy endpoints |
|---|---|---|
| Anonymous, per address | 90 a minute (burst 60) | 15 a minute (burst 10) |
| Free key | 600 a minute (burst 200) | 120 a minute (burst 40) |

**Heavy** endpoints are `search`, `changes`, `qa`, `occurrences`, `compare`, `trend`, `export`, the `events` list and `status`, plus the MCP tools `search`, `changes`, `history`, `get_qa` and `list_events`. Everything else, including full text (`appearances/<id>/text`) and single events, is normal. There is no daily cap. An MCP request costs one request per tool call.

API responses carry `RateLimit` and `RateLimit-Policy` headers. Over the limit you get `429` with `Retry-After`. Send a key in the `X-Parrot-Key` header, never in the URL. Ask for one at [ox@mail.grokbot.com](mailto:ox@mail.grokbot.com?subject=Parrot).

Please send a descriptive `User-Agent` with a contact, for example `my-agent/1.0 (you@example.com)`.

## Errors

JSON `{"error": code, "detail": ...}` with `400` for bad parameters, `404` for unknown ids, `429` for limits.

## Full text

Full transcripts are served only for public-domain and openly licensed sources. Everything else returns counts and short quotes. See [Sources](/sources).

## Stability

`/api/v1` is stable. We add fields and endpoints without notice; we do not remove or rename them without 90 days' notice on the [Changelog](/changelog). Entity, event and word ids are stable slugs.

## Terms

You may query Parrot and build tools and agents on it within the rate limits. Parrot's own data (counts, rates, settlement history, probabilities and QA results) is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): credit "parrot.markets" with a link. Transcripts, quotes and media are not covered: their rights stay with each source (see [Sources](/sources)). Use is subject to the [Terms](/terms). Not financial advice. Rates and probabilities are base rates from history, not forecasts. People who run Parrot trade on Kalshi and Polymarket, including mention markets.