Search and topics

Search finds events for free text and never comes back empty; topics group events by the people, teams, places and subjects they are labeled with; related-by-meaning lists events close to one you are looking at. This page covers how each works, what the labels mean, and the plain-language filters search understands. You need it when the way in is a phrase rather than an id.

Search

GET /v1/search?q=… returns events, each labeled with how it was found, strongest first:

`match`	Meaning
`match`	Every word matched a title, outcome or category, allowing common shorthand and the last word as a prefix so results follow typing; or the query names a person, team, place or subject the event is labeled with, however its title is worded.
`similar`	Some of the words matched, a title is close in spelling, or the event means nearly the same thing.
`related`	Trending in the category the query is about, named in `related_category`.
`trending`	Trending anywhere, most traded first.

curl "https://api.routeur.app/v1/search?q=chiefs&limit=3" \
  -H "X-API-Key: $ROUTEUR_API_KEY"

{
  "data": [
    { "match": "match", "event": { "venue": "kalshi", "id": "KXNFLGAME-26SEP20INDKC", "title": "IND Colts vs KC Chiefs", "…": "…" } },
    { "match": "match", "event": { "venue": "kalshi", "id": "KXNFLTD-26SEP20INDKC", "title": "Indianapolis vs Kansas City: Touchdowns", "…": "…" } },
    { "match": "match", "event": { "venue": "kalshi", "id": "KXNFLRSHYDS-26SEP20INDKC", "title": "Indianapolis vs Kansas City: Rushing Yards", "…": "…" } }
  ],
  "graph_run": 74,
  "next_offset": 3,
  "query": "chiefs",
  "filters": []
}

“Chiefs” finds Indianapolis vs Kansas City: events are labeled with the teams, people and places they are about, so a nickname finds a title that never uses it.

Parameter	Type	Default	Meaning
`q`	string, up to 200 characters		What to look for. Empty lists what is trending.
`limit`	integer, 1 to 50	`20`	Results per page.
`offset`	integer, 0 to 300	`0`	Pass the previous response’s `next_offset`.
`venue`	`kalshi`, `polymarket`		Only events on this venue. Wins over a venue named in `q`.
`category`	a category		Only events in this category.
`cross_venue`	boolean	`false`	Only events listed on both venues.
`closing`	`1`, `7`, `30`		Days ahead the event must close within.
`price_min`, `price_max`	integer, 0 to 100		Bounds on the leading outcome’s Yes price, in cents.
`min_volume`	integer		Least traded in the last 24 hours, in USD.
`moved`	boolean	`false`	Only events whose leading outcome moved 5¢ or more today.

Response field	Meaning
`query`	What was searched for once filters were taken out.
`corrected_query`	The query with misspelled words replaced by the closest word listings use.
`filters`	The filters in force, each with `kind`, a `label` to show and its `value`.
`related_category`	The category `related` results come from.
`next_offset`	Pass as `offset` for the next page. Pages go up to 300 results.

How results are found

Words are matched against titles, outcome labels and categories. Shorthand is expanded on the way: dems and gop to the parties, btc, eth, sol, xrp and doge to the coins, fed and fomc to each other, cpi and inflation to each other, potus, scotus, nfl, nba, mlb, nhl, epl, uk, us and a few more. Labels come first; then exact words; then close spellings; then meaning, from the same embeddings related events use. Thin events are ranked below events that can be traded, not hidden. The same question listed on both venues without a proven twin appears once. Words of four letters or more that no listing uses are replaced by the closest term listings do use, and the result is reported in corrected_query. Responses are cached for 30 seconds.

Plain-language filters

Words that describe a filter are read as one, cut out of the query, and reported in filters:

curl -G "https://api.routeur.app/v1/search" \
  --data-urlencode "q=dem senate races closing this month under 30c" \
  -H "X-API-Key: $ROUTEUR_API_KEY"

{
  "query": "dem senate races",
  "filters": [
    { "kind": "closing", "label": "Closing this month", "value": "30" },
    { "kind": "price", "label": "Under 30¢", "value": "0-30" }
  ],
  "data": [ "…" ]
}

Phrase	Filter
`kalshi`, `polymarket`	`venue`
`on both venues`, `both venues`, `cross-venue`	`cross_venue`
`closing`, `ending`, `resolving` or `expiring` plus `today`, `tonight`, `tomorrow`, `this week`, `this month`, `soon`	`closing`: 1 day for today and tonight, 2 for tomorrow and soon, 7 for this week, 30 for this month
`under 30c`, `below 30¢`, `less than 30%`	`price_max`
`over 60c`, `above 60¢`, `more than 60%`	`price_min`
`20 to 40c`, `20-40¢`	`price_min` and `price_max`
`longshots`, `underdogs`	under 20¢
`coin flips`, `toss ups`, `50/50`	40¢ to 60¢
`favorites`, `near certain`, `locks`	over 80¢
`over $50k traded`, `at least $2m volume`	`min_volume`
`liquid`, `busy`, `active`, `heavily traded`	at least $10,000 traded
`movers`, `moved`, `swung`	`moved`

Parameters win over words. With filters on, results can be empty: they are what you asked for.

Topics

Every listed event is labeled with the names it is about. GET /v1/topics lists the most common, with their category, what they traded today and their leading event; GET /v1/topics/{slug} returns the events labeled with one, most traded first, with the names that appear beside it most often.

curl "https://api.routeur.app/v1/topics/kansas-city-chiefs?limit=2" \
  -H "X-API-Key: $ROUTEUR_API_KEY"

{
  "data": {
    "name": "kansas city chiefs",
    "slug": "kansas-city-chiefs",
    "related": ["nfl", "sports", "american football", "indianapolis colts", "las vegas raiders", "los angeles chargers", "afc west", "…"],
    "events": [
      { "venue": "kalshi", "id": "KXNFLGAME-26SEP20INDKC", "title": "IND Colts vs KC Chiefs", "volume_24h_usd": "18736.52", "…": "…" },
      { "venue": "kalshi", "id": "KXNFLTD-26SEP20INDKC", "title": "Indianapolis vs Kansas City: Touchdowns", "volume_24h_usd": "12218.48", "…": "…" }
    ]
  },
  "graph_run": 74
}

Endpoint	Parameters	Notes
`GET /v1/topics`	`category`; `limit` 1 to 200, default 40	Names carried by at least two events, most common first. Each carries `events`, `volume_24h_usd`, `category`, `leading`, `image_url` and `cross_venue`, the count of its events on both venues.
`GET /v1/topics/{slug}`	`limit` 1 to 60, default 30	A slug is the name lowercased with hyphens between words, at most eight words, such as `democratic-party` or `us-elections`. `related` holds up to twelve co-occurring names. An unknown slug returns `404` with `topic_not_found`.

Events carry their own topics, at most six names, so any event opens onto its topic pages. GET /v1/events/{venue}/{id}/related and GET /v1/markets/{venue}/{id}/related return open events that mean something close to the one given, for “more like this”. Unlike relations, nothing here is proven: two related events can resolve independently.

curl "https://api.routeur.app/v1/events/kalshi/KXNFLGAME-26SEP20INDKC/related?limit=2" \
  -H "X-API-Key: $ROUTEUR_API_KEY"

{
  "data": [
    { "similarity": 0.8808, "reason": { "kind": "topic", "label": "nfl", "text": "Same topic: NFL" }, "event": { "venue": "kalshi", "id": "KXNFLSPREAD-26SEP20INDKC", "title": "Indianapolis vs Kansas City: Spread", "…": "…" } },
    { "similarity": 0.8792, "reason": { "kind": "entity", "label": "indianapolis colts", "text": "Also about Indianapolis Colts" }, "event": { "venue": "polymarket", "id": "827222", "title": "Indianapolis vs Kansas City: Total Points", "venues": ["kalshi", "polymarket"], "…": "…" } }
  ],
  "graph_run": 74
}

Parameter	Type	Default	Meaning
`limit`	integer, 1 to 24	`6`	Related events to return.
`cross_venue`	boolean	`false`	Only related events listed on both venues.

Field	Meaning
`similarity`	Cosine similarity of the two events’ embeddings, built from title, outcomes and labels. Above about 0.8 the events are about the same thing.
`reason.kind`	Why it is related, strongest first: `series`, another instance of the same recurring question; `team`, two games with a team in common; `entity`, the same person, organization, place or asset; `topic`, the same narrow subject; `meaning`, no label in common but very close in meaning.
`reason.label`	The shared name, lowercase as labeled. Absent for `series` and `meaning`.
`reason.text`	Ready to show: `Same team: Kansas City Chiefs`.

What comes back is filtered to be worth a look:

Only events that can still be traded: closed events, games under way, and one-winner events whose leading outcome costs 97¢ or more are left out, as are the event itself, its twin, and the same question on the other venue without a proven twin.
A neighbour is kept when it is very close in meaning, or reasonably close and shares a labeled name or subject with the event. A match on meaning alone must be very close.
Instances of one recurring question collapse to the best of them: every day of a price range, or every game of the same team, shows once. At most one other instance of the event’s own series is kept, ranked below new questions.
Order is by similarity, nudged up for what traded today and down for anything under $1,000.

An event not yet labeled has no related events. Results are cached for two minutes.

GET /v1/markets?q= is a different tool: it searches market titles by spelling similarity and pages by cursor, for when you need individual markets rather than events. GET /v1/events?q= matches event titles only, with no filters or labels.

Events and markets: what an event carries.
Relations: what is proven, as opposed to related by meaning.
Signals: what is trending, moving and closing.
Pagination: offsets and cursors.

Get started

Concepts

Agents & MCP

Webhooks

Reference

Search and topics

Search

How results are found

Plain-language filters

Topics

Search

How results are found

Plain-language filters

Topics

Related by meaning

Related