> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oddpool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search markets

> Find markets by text query, by series, or both.

You must pass **either `q` or `series_id`** (or both). Requests with neither return `400`.

Use `q` for free-text search and `series_id` to scope results to one series. If you don't have a `series_id` yet, find one via [Search series](/search/series). To list every outcome under a single known event, use [Event markets](/search/event-markets) instead.

## Parameters

<ParamField query="q" type="string">
  Full-text search on `question`. Required when `series_id` is not provided.
</ParamField>

<ParamField query="series_id" type="string">
  Filter to one series. Examples: `KXBTC15M`, `btc-up-or-down-15m`, `KXFEDDECISION`. Required when `q` is not provided.
</ParamField>

<ParamField query="exchange" type="string">
  `kalshi` or `polymarket`.
</ParamField>

<ParamField query="status" type="string" default="active">
  `active` (still trading) or `closed` (settled with a result).
</ParamField>

<ParamField query="category" type="string">
  Exact category match.
</ParamField>

<ParamField query="min_volume" type="integer">
  Minimum volume.
</ParamField>

<ParamField query="min_liquidity" type="integer">
  Minimum liquidity.
</ParamField>

<ParamField query="settled_after" type="string">
  ISO timestamp. Returns markets with `settled_at >= settled_after`. Pair with `status=closed` for backtest workflows.
</ParamField>

<ParamField query="settled_before" type="string">
  ISO timestamp. Returns markets with `settled_at <= settled_before`.
</ParamField>

<ParamField query="discovered_after" type="string">
  ISO timestamp filter on `discovered_at`. For polling new listings.
</ParamField>

<ParamField query="sort_by" type="string" default="relevance">
  `relevance`, `newest`, `volume`, or `liquidity`. `relevance` requires `q`; without `q` the default is `newest`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  1-100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset. The response is a bare JSON array — increment `offset` by `limit` until you receive an empty array.
</ParamField>

## Examples

### Settled-window discovery for a backtest

List the closed markets that resolved in a window for a known series. The returned `market_id` values feed directly into the [Kalshi historical](/kalshi/overview) endpoints.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://api.oddpool.com/search/markets?series_id=KXBTC15M&status=closed&settled_after=2026-04-25T00:00:00Z&limit=100"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.oddpool.com/search/markets",
      headers={"X-API-Key": "your_api_key"},
      params={
          "series_id": "KXBTC15M",
          "status": "closed",
          "settled_after": "2026-04-25T00:00:00Z",
          "limit": 100,
      },
  )
  markets = response.json()
  ```
</CodeGroup>

### Free-text search

Filter markets across series by keyword. Sort by volume to surface the most active.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://api.oddpool.com/search/markets?q=fed+rate&exchange=kalshi&sort_by=volume"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.oddpool.com/search/markets",
      headers={"X-API-Key": "your_api_key"},
      params={"q": "fed rate", "exchange": "kalshi", "sort_by": "volume"},
  )
  markets = response.json()
  ```
</CodeGroup>

## Response

```json theme={null}
[
  {
    "market_id": "KXBTC15M-26MAY020000-00",
    "exchange": "kalshi",
    "series_id": "KXBTC15M",
    "question": "BTC price up in next 15 mins?",
    "category": null,
    "status": "closed",
    "volume": 375089,
    "liquidity": 119393,
    "last_yes_price": "0.9990",
    "last_no_price": "0.0000",
    "event_id": "KXBTC15M-26MAY020000",
    "event_title": "BTC 15 min · $78,396.72 target",
    "slug": null,
    "discovered_at": "2026-05-01T03:50:00Z",
    "settled_at": "2026-05-02T04:00:26Z"
  }
]
```

## Errors

| Code  | Reason                                |
| ----- | ------------------------------------- |
| `400` | Neither `q` nor `series_id` provided. |