Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Prediction API

Unified search (events / tags / profiles)

/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.
get/v4/data/prediction/search

Query parameters

qstring required
Example:election

Search string (required). 2..128 characters. Single-character queries are rejected with 400.

pageinteger
Example:1

1-indexed page number for paging through results. Defaults to 1.

limitPerTypeinteger
Example:10

Maximum number of results per branch (events / tags / profiles). Defaults to 10.

searchTagsboolean
Example:true

Toggle the tags branch. Defaults to true.

searchProfilesboolean

Toggle the profiles branch. Defaults to false — most callers don't need profile results.

eventsStatusstring
Example:active

Narrow the events branch by status (free-text — accepts any value the upstream supports, e.g. active).

eventsTagstring
Example:politics,sports

Narrow the events branch to a comma-separated list of tag slugs. Up to 50 entries.

keepClosedMarketsboolean

Include closed markets in the events branch. Defaults to the upstream's behaviour (closed markets are hidden).

sortstring
Example:volume

Sort key forwarded to the upstream (free-text — accepts comma-separated field names).

ascendingboolean

Sort direction.

Response

OK

Example response

{
  "data": {
    "events": [
      {
        "id": "KXELONMARS",
        "platform": "polymarket",
        "title": "Will Elon Musk land humans on Mars by 2030?",
        "description": "Outcome resolves on confirmation of a successful crewed Mars landing.",
        "category": "Science",
        "tags": [
          "space",
          "spacex"
        ],
        "imageUrl": "https://polymarket.com/images/elon-mars-event.png",
        "status": "active",
        "openTime": "2024-01-01T00:00:00Z",
        "closeTime": "2030-12-31T23:59:59Z",
        "marketCount": 3,
        "totalVolume": 4823100.5,
        "volumeUnit": "usd",
        "totalLiquidity": 271800.3,
        "markets": [
          "KXELONMARS-99"
        ],
        "source": {
          "platform": "polymarket",
          "platformId": "KXELONMARS-99",
          "url": "https://kalshi.com/markets/kxelonmars"
        }
      }
    ],
    "tags": [
      {
        "id": "101",
        "slug": "us-elections",
        "label": "US Elections",
        "eventCount": 42
      }
    ],
    "profiles": [
      {
        "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
        "name": "JaneDoe",
        "pseudonym": "WitnessProtection"
      }
    ],
    "pagination": {
      "hasMore": true,
      "totalResults": 184
    }
  }
}