Free-text search. q may mix team names, player names and a market intent
("Lakers moneyline", "Raiders player props", "Mahomes passing yards").

Types. types is a comma-separated subset of team,player,event,market
(default all). types=team,player,event never reads odds and is the typeahead
path; agree a client debounce of about 300 ms. market attaches canonical
markets to the matched events. Each quote is the GET /v1/odds row with the
same metadata.execution, deep_link, limits and canonical_outcome_id;
line_alignment (prediction-market line ladder) is not included in v1.

Matching. Teams match on name, market, nickname, abbreviation and
market + nickname (exact, then prefix, then typo-tolerant). Ambiguous names
("Giants", "Kings") return every candidate; nothing is guessed. Colloquial
soccer names that are not in the team record ("Wolves", "Spurs") can miss.
Players match on full name and, for a single word, family name. Players are
found through posted player markets; a player with none in the window (for
example "Aaron Rodgers" before his game's props are posted) falls back to the
events of the player's current team when the name matches exactly (or the result
is at most 10 players), so the upcoming game is still returned with the team's
board. A bare surname with many players does not.

Ranking. Only leagues your tenant is entitled to are searched. With
event or market in types, hits with no event in the window are dropped.
Events sort live first, then scheduled_time, then common_model_id; teams
and players sort by their earliest event, then match quality; players with no
event are ordered by whether their current team plays in the window, then match
quality, then league id, then common_model_id. There is no league-tier
heuristic.

Window. Default now to now+14 days, plus live (in-progress) events that
started within the last 24 hours; a multi-day event that started earlier is not
returned. start_date/end_date (ISO 8601 or YYYY-MM-DD, UTC) replace it
(live events are then not added). end_date may be at most 60 days after
start_date: a date-only end_date includes that whole day but counts to the
start of it, so 2026-01-01..2026-03-02 is accepted and ..2026-03-03 is not;
datetimes are compared exactly (60 days to the microsecond is accepted).
Cancelled and postponed events are excluded.

Candidate caps. Resolution is bounded: at most 24 candidate teams (a nickname
shared by more, such as "Eagles", is ranked first: teams with an event in the
window, then match quality, then nearest event), 50 events
per team, 600 name matches per player lookup, 10 players, 10 teams returned and
200 candidate events. meta.candidates_truncated is true when any cap cut the
set. Players are counted as distinct people, not source rows. A very wide
name prefix (more than 600 distinct players, e.g. a very common surname such as
"smith") is answered by exact full-name match only, so it may return no players
with candidates_truncated: true; add a first name or initial to narrow it.
Team matching is exact, then prefix, then typo-tolerant with a tight bound (one
edit for 5-8 character names, two from 9, an adjacent swap counts as one; none
under 5 characters; abbreviations are exact only). meta.incomplete_resolution is true when a resolution read failed or timed
out: results may be missing entities or events (such answers are never cached).

Odds reads. Every odds read is scoped to one event; there is never a
league-wide read. aggregator has the same semantics as
GET /v1/odds?event_id=&aggregator= on the plane the deployment serves.
With no market intent (neither a market phrase in q nor market_type) the
board is the core category (moneyline, spreads, totals and their period
variants); name a market or category to see others (meta.query.market_intent .default_scope is core in that case). Per event at most 25 markets, 20
outcomes per market and 5 quotes per outcome are returned, and at most 2,000
quotes per response; truncated and meta.truncated_event_ids say when a cap
cut a board. When more than 3 teams resolved (an ambiguous nickname such as
"Panthers" or "Eagles") each board is cut to 10 markets instead of 25, to keep the
response small. When a board has more than 25 markets the 25 are chosen round-robin
across market types (the best covered line of each type first), so one type does
not fill the board. The player-prop markets of a board are scoped to the entity in
q: the named player(s) that play in that event, or the roster of the named
team(s) playing in it (a roster is the players whose latest team it is, not every
player who was ever listed with it); team, game and event markets (for example in
"Mahomes props") are read unscoped. An event whose roster is missing or over the
per-team cap, or that no ranked player plays in, stays unscoped and is listed in
meta.unscoped_event_ids; so is an event whose scoped player-prop read found no
rows at all and was read once more unscoped (and then returned rows). The read is bounded at 3,000 rows per pass; when a
pass is cut, the market types it did not reach are read again (at most 3 passes
per event). truncated.rows is true when rows were left unread, in which case
total_markets is a partial count. Quotes older than the configured maximum
quote age (default 24 hours) are removed from the boards and counted in
meta.stale_quotes_dropped (an event whose quotes are all stale is returned with
markets: []; kalshi and prophetx quotes are exempt because their timestamps are
not proven to advance on an unchanged re-poll); GET /v1/odds is unaffected. Read the full board with
GET /v1/odds?event_id=. Events whose read timed out, or that could not be read
back, are listed in meta.incomplete_event_ids with markets: [].

Paging. limit is events per page (default 10, max 25). Follow
meta.next_cursor while meta.has_next_page. Cursors are bound to the tenant
and to every filter, expire after 15 minutes, and are rejected with
invalid_cursor (reason: expired, tenant, filter_mismatch,
page_size_mismatch, malformed). Paging is stable within the resolution
cache window and best-effort beyond it.

Responses are private, no-store. Overload, a cold team index and an
unavailable feature-flag or event read return 503 with retry-after.