---
title: "Unified search (events / tags / profiles)"
method: GET
path: "/v4/data/prediction/search"
tags: ["Prediction API"]
---

# Unified search (events / tags / profiles)

`GET /v4/data/prediction/search`

/v4/data/prediction/search

**50 credits per API call**

Unified search across events, tags and trader profiles. One query returns all three result types in a single response — pick the branches you care about with `searchTags` and `searchProfiles`. Designed for discovery surfaces (autocomplete, top-of-page search) where a single query needs to surface the most relevant entities of any kind.

**Platform support**

*   Polymarket only.

**Filtering and pagination**

*   `q` is the required search string — 2..128 characters. Single-character queries are rejected with `400` because they match an unhelpfully wide slice of the dataset.
*   `limitPerType` caps the number of results returned per branch (events, tags, profiles) — defaults to 10.
*   `searchTags` toggles the `tags` branch — defaults to `true`. `searchProfiles` toggles the `profiles` branch — defaults to `false` because most callers don't need it.
*   `eventsStatus` narrows the events branch by a free-text status (e.g. `active`); `eventsTag` is a comma-separated list of tag slugs (up to 50 entries). `keepClosedMarkets` overrides the default behaviour of hiding closed markets from the events branch.
*   `sort` is a free-text sort key forwarded to the upstream; `ascending` sets sort direction.
*   Pagination is page-based (not cursor-based) — advance via `?page=N+1`. The response body carries `data.pagination.hasMore` and `data.pagination.totalResults` for paging decisions.

**Other notes**

*   Branches are populated independently — an empty `tags` array means no tag matches were found, not that the search failed.
*   `events` share the same shape as the `/events` listing endpoint, so the same client-side rendering can be reused.
*   `profiles` rows include only `proxyWallet`, `name` and `pseudonym` — additional profile fields (image, bio) are not exposed here.

## Query parameters

- `q` string, required
- `page` integer
- `limitPerType` integer
- `searchTags` boolean
- `searchProfiles` boolean
- `eventsStatus` string
- `eventsTag` string
- `keepClosedMarkets` boolean
- `sort` string
- `ascending` boolean

## Response `200`

OK

- PredictionSearchResponse — Unified-search response.
  - `data` PredictionSearchResult, required — Unified-search payload — events, tags and trader profiles for a single query, with native page-based pagination.
    - `events` PredictionEvent[], required — Matching events. Same shape as the rows returned by `/events`. Empty when no event matches are found.
      - `id` string, required — Platform-native event identifier (Polymarket numeric id or Kalshi event ticker).
      - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
      - `title` string, nullable, required — Event title.
      - `description` string, nullable, required — Long-form event description, when available.
      - `category` string, nullable, required — Event category label, when available.
      - `tags` string[], required — Free-form tag slugs. May be empty on Kalshi.
      - `imageUrl` string, nullable, required — Image / icon URL for the event, when available.
      - `status` string, required — Verbatim upstream status string. Richer than the `?status=` filter enum.
      - `openTime` string, date-time, nullable, required
      - `closeTime` string, date-time, nullable, required
      - `marketCount` integer, required — Number of markets attached to this event.
      - `totalVolume` number, required — Sum of nested-market volume, in `volumeUnit` units.
      - `volumeUnit` 'usd' | 'contracts', required — Unit for `volume` and `totalVolume` fields. `usd` on Polymarket (dollar-denominated notional); `contracts` on Kalshi (contract count — not USD).
      - `totalLiquidity` number, nullable, required — Sum of nested-market quoted liquidity. `null` on Kalshi events because the underlying market liquidity is not exposed there.
      - `markets` union[], required — The event's markets. **Never null.** - When the request passes `includeMarkets=true`, each entry is a full market object. - Otherwise (default, `includeMarkets=false`), each entry is a **market ID string**. The id is exactly what the get-market-by-id endpoint accepts — copy an id and call `GET /v4/data/prediction/markets/{id}` to fetch that market's full details.
        - union
          - string — Market ID — pass to `GET /v4/data/prediction/markets/{id}`.
          - PredictionEventMarket — Market row as nested inside an event. Same shape as the top-level `PredictionMarket` minus the `chain` block (which is only surfaced on the dedicated markets endpoints).
            - `id` string, required — Platform-native market identifier (Polymarket condition id or Kalshi market ticker).
            - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
            - `eventId` string, nullable, required — Parent event id. Polymarket numeric event id, or Kalshi event ticker. `null` when the upstream does not group this market under an event.
            - `question` string, required — Human-readable market question.
            - `description` string, nullable, required — Long-form description or resolution rules.
            - `category` string, nullable, required — Category label, when available.
            - `tags` string[], required — Free-form tag slugs. May be empty on Kalshi.
            - `imageUrl` string, nullable, required — Image / icon URL for the market, when available.
            - `status` string, required — Verbatim upstream status string. Richer than the `?status=` filter enum — values can include `paused`, `archived`, `settled`, `determined`, etc.
            - `openTime` string, date-time, nullable, required — ISO-8601 timestamp the market opened for trading.
            - `closeTime` string, date-time, nullable, required — ISO-8601 timestamp the market closes / closed for trading.
            - `settleTime` string, date-time, nullable, required — ISO-8601 timestamp the market is expected to settle.
            - `outcomes` PredictionMarketOutcome[], required — All outcomes of the market.
              - …
            - `volume` number, required — Total volume in `volumeUnit` units.
            - `volumeUnit` 'usd' | 'contracts', required — Unit for `volume` and `totalVolume` fields. `usd` on Polymarket (dollar-denominated notional); `contracts` on Kalshi (contract count — not USD).
            - `liquidity` number, nullable, required — Quoted-resting-orders depth. `null` on Kalshi — the upstream markets feed does not populate this; aggregate orderbook depth client-side if you need it.
            - `resolution` PredictionMarketResolution, required — Resolution payload populated only after a market has settled. `null` on every active or paused market.
              - …
            - `createdAt` string, date-time, nullable, required — ISO-8601 timestamp the market was created upstream.
            - `source` PredictionMarketSource, required — Upstream platform attribution for a market or event row.
              - …
      - `source` PredictionMarketSource, required — Upstream platform attribution for a market or event row.
        - `platform` 'polymarket' | 'kalshi', required — Prediction-market platform identifier.
        - `platformId` string, required — Platform-native identifier. Polymarket condition id (0x + 64 hex) or numeric event id; Kalshi market or event ticker.
        - `url` string, required — Canonical public URL on the source platform.
    - `tags` PredictionSearchTag[], required — Matching tags. Empty when `searchTags=false` or no tag matches are found.
      - `id` string, nullable, required — Tag identifier, when the upstream populates it.
      - `slug` string, nullable, required — URL-friendly tag slug.
      - `label` string, nullable, required — Human-readable tag label.
      - `eventCount` integer, required — Authoritative count of events this tag is attached to.
    - `profiles` PredictionSearchProfile[], required — Matching trader profiles. Empty when `searchProfiles=false` (default) or no profile matches are found.
      - `proxyWallet` string, required — Profile wallet (0x + 40 hex, lowercased).
      - `name` string, nullable, required — Profile display name, when set.
      - `pseudonym` string, nullable, required — Profile pseudonym, when set.
    - `pagination` PredictionSearchPagination, required — Page-based pagination metadata used by the search endpoint. Caller advances with `?page=N+1` and stops when `hasMore` is `false`.
      - `hasMore` boolean, required — Whether a subsequent page exists.
      - `totalResults` integer, required — Total number of results across all pages.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/versions/8622ee4b8fae/schema)