GET
/api/v1/markets/search
Search covered markets by meaning, text, tags, or categories
Hybrid discovery over active Quotient-covered markets. With as_of it becomes a point-in-time search over markets having coverage at or before the cutoff, including markets that have since closed. It fuses graph text/tag matches with optional lexical and embedding recall. Each market includes Q's latest committed probability and paired thesis at or before the cutoff, forecast_at, the forecast-time venue quote, response-time market_odds, venue_quote provenance, and explicit forecast/published-signal availability. Polymarket International and Kalshi use a verified live quote or null; Polymarket US and Limitless expose a graph snapshot marked stale. For a historical spread compare latest_q_probability with market_odds_at_forecast. A published signal may be historical and is not necessarily active now. Relevance scores order only this response; they are not probabilities. Supply q, tag, or category; q defaults to '*' for filter-only searches. By default results are windowed to forecasts from the last 168 hours (markets with a published signal stay); widen or effectively disable with max_forecast_age.
Price $0.01Auth x-quotient-api-key or x402Limit 20/s · 600/min · 20,000/day
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| q | query | string | Natural-language or keyword query. Optional when tag or category is supplied. Minimum length: 1; Maximum length: 200 |
| tag | query | string[] | Case-insensitive Event/market tag filter. Repeat the parameter or comma-separate values; any supplied tag may match. Maximum items: 10 |
| category | query | string[] | Case-insensitive category filter. Repeat the parameter or comma-separate values; any supplied category may match. Maximum items: 10 |
| 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. |
| as_of | query | string | Optional inclusive historical cutoff. Accepts YYYY-MM-DD (expanded to 23:59:59.999 UTC that day) or an RFC 3339 date-time with Z or an explicit offset. Omit for the current view. |
| max_forecast_age | query | integer | Maximum forecast age in hours, anchored at as_of (or now). Rows whose only Q claim is a forecast older than this window are dropped; markets with a published signal stay, matching the catalog route. Default: 168 (7 days). Set a large value (e.g. 8760) to effectively disable windowing. Default: 168; Minimum: 1 |
| group_by | query | "market" | "event" | Set event to additionally group the returned matches by parent Event. The markets array is present. Default: "market" |
Responses
200: Ranked covered-market matches at the stated snapshot cutoff
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| as_of required | string | Inclusive snapshot cutoff applied to forecast and publication selection. Format: date-time | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| historical required | boolean | True when the caller supplied as_of; false for the current view. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| query required | string | Normalized search query, or '*' for a filter-only search. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| group_by required | "market" | "event" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| markets required | MarketSearchItem[] | markets fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| events required | MarketSearchEventGroup[] | null | Returned matches grouped by Event when group_by=event; otherwise null.events fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| facets required | object | Taxonomy counts across the returned hydrated candidate set.facets fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| retrieval required | object | Per-lane health. Graph retrieval is required; optional lanes fail open to graph results.retrieval fields
|
401: Unauthorized
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
402: Payment Required
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
403: Insufficient credits for the requested route
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
422: Invalid query, filters, grouping, or venue
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
429: The caller exceeded a per-second, per-minute, daily, or concurrency limit. No credits are debited and no x402 payment is settled for this response.
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
Set QUOTIENT_API_KEY in your shell and replace example identifiers with returned IDs before running a request.
curl
curl --request GET \
--header "x-quotient-api-key: $QUOTIENT_API_KEY" \
'https://quotient-api-gateway.onrender.com/api/v1/markets/search'200 · application/json
{
"as_of": "2027-01-01T00:00:00Z",
"historical": false,
"query": "example",
"group_by": "market",
"markets": [
{
"venue": "polymarket",
"nativeMarketId": "example",
"nativeEventId": "example",
"seriesTicker": "example",
"marketKey": "example",
"quotientMarketId": "example",
"slug": "example",
"marketUrl": "example",
"sourceUrl": "example",
"broker_channels": [
"robinhood"
],
"robinhood_category": "example",
"robinhood_url": "example",
"question": "example",
"event": {
"id": "example",
"title": "example",
"slug": "example"
},
"tags": [
"example"
],
"categories": [
"example"
],
"end_date": "2027-01-01T00:00:00Z",
"market_odds": 0,
"venue_quote": {
"schema_version": "1",
"venue": "polymarket",
"market_id": "example",
"yes_bid": 0,
"yes_ask": 0,
"yes_last": 0,
"selected_probability": 0,
"quote_method": "example",
"venue_timestamp": "2027-01-01T00:00:00Z",
"observed_at": "2027-01-01T00:00:00Z",
"freshness": "verified"
},
"inDispute": false,
"clarifications": "example",
"volume_24h": 0,
"signal_count": 0,
"forecast_count": 0,
"latest_forecast_at": "2027-01-01T00:00:00Z",
"market_updated_at": "2027-01-01T00:00:00Z",
"latest_forecast_delta": 0,
"latest_forecast_refresh_reason": "example",
"forecast_status": {
"state": "warning",
"cents": 0,
"adverse_move_pct": 0,
"basis": "since_publish",
"price_source": "live"
},
"quotientUrl": "example",
"polymarketUrl": "example",
"relationships": {
"assets": [
{}
],
"markets": [
{}
],
"signals": [
{}
],
"truncated": {
"assets": false,
"markets": false,
"signals": false
}
},
"has_forecast": false,
"latest_q_probability": 0,
"thesis": "example",
"forecast_at": "2027-01-01T00:00:00Z",
"market_odds_at_forecast": 0,
"has_published_signal": false,
"published_signal_count": 0,
"relevance": {
"score": 0,
"matched_by": [
"graph"
],
"matched_fields": [
"example"
]
}
}
],
"events": [
{
"event": {
"id": "example",
"title": "example",
"slug": "example"
},
"tags": [
"example"
],
"categories": [
"example"
],
"relevance": {
"score": 0,
"matched_by": [
"graph"
],
"matched_fields": [
"example"
]
},
"markets": [
{
"venue": "polymarket",
"nativeMarketId": "example",
"nativeEventId": "example",
"seriesTicker": "example",
"marketKey": "example",
"quotientMarketId": "example",
"slug": "example",
"marketUrl": "example",
"sourceUrl": "example",
"broker_channels": [
null
],
"robinhood_category": "example",
"robinhood_url": "example",
"question": "example",
"event": {
"id": null,
"title": null,
"slug": null
},
"tags": [
null
],
"categories": [
null
],
"end_date": "2027-01-01T00:00:00Z",
"market_odds": 0,
"venue_quote": {
"schema_version": null,
"venue": null,
"market_id": null,
"yes_bid": null,
"yes_ask": null,
"yes_last": null,
"selected_probability": null,
"quote_method": null,
"venue_timestamp": null,
"observed_at": null,
"freshness": null
},
"inDispute": false,
"clarifications": "example",
"volume_24h": 0,
"signal_count": 0,
"forecast_count": 0,
"latest_forecast_at": "2027-01-01T00:00:00Z",
"market_updated_at": "2027-01-01T00:00:00Z",
"latest_forecast_delta": 0,
"latest_forecast_refresh_reason": "example",
"forecast_status": {},
"quotientUrl": "example",
"polymarketUrl": "example",
"relationships": {
"assets": null,
"markets": null,
"signals": null,
"truncated": null
},
"has_forecast": false,
"latest_q_probability": 0,
"thesis": "example",
"forecast_at": "2027-01-01T00:00:00Z",
"market_odds_at_forecast": 0,
"has_published_signal": false,
"published_signal_count": 0,
"relevance": {
"score": null,
"matched_by": null,
"matched_fields": null
}
}
]
}
],
"facets": {
"tags": [
{
"value": "example",
"count": 1
}
],
"categories": [
{
"value": "example",
"count": 1
}
]
},
"retrieval": {
"graph": "ok",
"typesense": "ok",
"semantic": "ok"
}
}