API
Read-only, free, no account. Base URL https://parrot.markets/api/v1. Full reference: /docs and /openapi.json. For MCP, see 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) |
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.
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.
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. 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: credit "parrot.markets" with a link. Transcripts, quotes and media are not covered: their rights stay with each source (see Sources). Use is subject to the 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.