GET
/api/v1/markets/search
Search covered markets by meaning, text, tags, or categories
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| q | query | string | Natural-language or keyword query. Optional when tag or category is supplied. |
| tag | query | string[] | Case-insensitive Event/market tag filter. Repeat the parameter or comma-separate values; any supplied tag may match. |
| category | query | string[] | Case-insensitive category filter. Repeat the parameter or comma-separate values; any supplied category may match. |
| venue | query | "polymarket" | "polymarket_us" | "kalshi" | "limitless" | Optional prediction-market venue filter. Omit it on catalog/feed routes to include every covered venue. On legacy slug or condition-ID lookups, omission retains the Polymarket namespace; prefer marketKey for collision-safe cross-venue lookup. |
| group_by | query | "market" | "event" | Set event to additionally group the returned matches by parent Event. The markets array is always present. |
Response fields
| Field | Type | Meaning |
|---|---|---|
| query | string | Normalized search query, or '*' for a filter-only search. |
| group_by | "market" | "event" | |
| markets | MarketSearchItem[] | |
| events | MarketSearchEventGroup[] | Returned matches grouped by Event when group_by=event; otherwise null. |
| facets | object | Taxonomy counts across the returned hydrated candidate set. |
| retrieval | object | Per-lane health. Graph retrieval is required; optional lanes fail open to graph results. |
Billing and limits
Calls are billed to prepaid credits, or per call over x402. The price above is the reference price; the 402 challenge returned at request time is what a call actually costs.
One request may be in flight at a time, and request starts must be at least one second apart. A rejected 429 is not billed. See rate limits.
curl
curl -H "x-quotient-api-key: qt_…" \
"https://quotient-api-gateway.onrender.com/api/v1/markets/search"Run sends this request with preset parameters on Quotient’s demo key. Your credits are not spent.
200 · application/json
{
"query": "…",
"group_by": "market",
"markets": [
{}
],
"events": [
{
"event": {
"id": "…",
"title": "…",
"slug": "…"
},
"tags": [
"…"
],
"categories": [
"…"
],
"relevance": {
"score": 0,
"matched_by": [
"graph"
],
"matched_fields": [
"…"
]
},
"markets": [
{}
]
}
],
"facets": {
"tags": [
{
"value": "…",
"count": 0
}
],
"categories": [
{
"value": "…",
"count": 0
}
]
},
"retrieval": {
"graph": "ok",
"typesense": "ok",
"semantic": "ok"
}
}