Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.codex.io/llms.txt

Use this file to discover all available pages before exploring further.

Prediction Market data is currently in beta. It is actively being worked on and improved, but may be unreliable. Polymarket and Kalshi data are live.At least for the time being, this endpoint requires a Growth or Enterprise plan. Learn more.
This endpoint requires a Growth or Enterprise plan. Learn more.

​
Returns

​
PredictionEventFilterConnection
PredictionEventFilterConnection
See PredictionEventFilterConnection

​
Arguments

​
filters
PredictionEventFilters
A set of filters to apply. See PredictionEventFilters
​
phrase
String
A phrase to search for. Can match event question, tags, or description.
​
eventIds
[String!]
A list of event IDs to filter by.
​
excludeEventIds
[String!]
A list of event IDs to exclude from results.
​
rankings
[PredictionEventRanking!]
A list of ranking attributes to apply. See PredictionEventRanking
​
marketSort
PredictionEventMarketSort
deprecated
Deprecated. No longer affects market ordering. See PredictionEventMarketSort
This field is deprecated. No longer affects market ordering.
​
limit
Int
The maximum number of events to return.
​
offset
Int
Where in the list the server should start when returning items.

​
Example: Top events by 24h volume

{
  filterPredictionEvents(
    rankings: [
      { attribute: volumeUsd24h, direction: DESC }
    ]
    limit: 10
  ) {
    count
    page
    results {
      id
      timestamp
      lastTransactionAt
      event {
        id
        venueEventId
        protocol
        status
        question
        description
        tags
        imageThumbUrl
        venueUrl
        createdAt
        opensAt
        closesAt
        resolvesAt
        resolvedAt
      }
      protocol
      status
      createdAt
      opensAt
      closesAt
      resolvesAt
      resolvedAt
      markets {
        id
        label
      }
      marketCount
      categories
      resolutionSource
      liquidityUsd
      volumeUsdAll
      volumeUsd24h
      volumeChange24h
      trades24h
      tradesChange24h
      uniqueTraders24h
      uniqueTradersChange24h
      liquidityChange24h
      openInterestUsd
      openInterestChange24h
      trendingScore24h
      relevanceScore24h
    }
  }
}
Example Response (truncated)
{
  "data": {
    "filterPredictionEvents": {
      "count": 10,
      "page": 0,
      "results": [
        {
          "id": "67284:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "protocol": "POLYMARKET",
          "status": "OPEN",
          "categories": [
            "economy",
            "finance",
            "politics",
            "sports",
            "fed"
          ],
          "marketCount": 4,
          "event": {
            "question": "Fed decision in March?",
            "description": null,
            "imageThumbUrl": "https://polymarket-upload.s3.us-east-2.amazonaws.com/jerome+powell+glasses1.png"
          },
          "liquidityUsd": "32307112",
          "volumeUsd24h": "15366655",
          "trades24h": 4952,
          "uniqueTraders24h": 2536,
          "trendingScore24h": 0.33556132554617574,
          "opensAt": 1761764679,
          "closesAt": 1773792000,
          "resolvesAt": 1773792000
        }
        // ... 9 more results
      ]
    }
  }
}

​
Example: Search events by text

{
  filterPredictionEvents(
    phrase: "Champions League"
    filters: {
      status: OPEN
      marketCount: { gt: 1 }
    }
    rankings: [
      { attribute: volumeUsd24h, direction: DESC }
    ]
    limit: 5
  ) {
    count
    results {
      event {
        question
        description
      }
      status
      categories
      marketCount
      liquidityUsd
      volumeUsd24h
      trendingScore24h
    }
  }
}

​
Example: Filter by category and status

{
  filterPredictionEvents(
    filters: {
      categories: ["sports", "basketball"]
      status: OPEN
      liquidityUsd: { gt: 100000 }
    }
    rankings: [
      { attribute: trendingScore24h, direction: DESC }
    ]
    limit: 10
  ) {
    count
    results {
      event {
        question
      }
      categories
      marketCount
      liquidityUsd
      volumeUsd24h
      uniqueTraders24h
      trendingScore24h
      closesAt
    }
  }
}

​
Example: Events closing soon

{
  filterPredictionEvents(
    filters: {
      status: OPEN
      closesAt: { gte: 1773000000, lte: 1774000000 }
    }
    rankings: [
      { attribute: closesAt, direction: ASC }
    ]
    limit: 20
  ) {
    count
    results {
      event {
        question
        imageThumbUrl
      }
      marketCount
      liquidityUsd
      volumeUsd24h
      opensAt
      closesAt
      resolvesAt
    }
  }
}

​
Usage Guidelines

  • Response limit: 100 events per request (configurable with limit parameter)
  • Use trendingScore24h or volumeUsd24h rankings for discovering active events
  • Apply quality filters like minimum liquidity (liquidityUsd: { gt: 10000 }) to focus on liquid events
  • Use phrase parameter to search by event question or description
  • Filter by status: OPEN to exclude resolved/closed events
  • Use categories filter to narrow down to specific topics (e.g., “sports”, “politics”, “crypto”)
  • marketCount shows how many individual markets are within the event

​
Event vs Market Structure

Events are collections of related markets. For example:
  • Event: “Champions League Final 2026”
    • Market 1: “Will Team A win?”
    • Market 2: “Will the score be over 2.5 goals?”
    • Market 3: “Will there be a penalty?”
Use filterPredictionEvents to find high-level topics, then drill into individual markets with filterPredictionMarkets.

​
Event Status Values

See the PredictionEventStatus enum for all possible status values and their meanings.

​
Scoring Metrics

  • trendingScore - Measures what’s “heating up” - prioritizes growth velocity over absolute size (a small event with 10x volume growth scores higher than a large event with flat volume)
  • relevanceScore - Measures what “matters” - based on absolute size and capital at stake across all markets, with no growth multipliers (large, established events rank high even if quiet)
  • competitiveScore - Measures genuine uncertainty across event markets - higher when prices are near 50%, trading is balanced on both sides, and there’s active price discovery

​
Troubleshooting Tips

Use the marketCount filter. Events with higher market counts offer more granular betting options. For example: marketCount: { gt: 5 } will return events with 6+ markets.
Use the change metrics like volumeChange24h, liquidityChange24h, and uniqueTradersChange24h. Positive values indicate growth. Combine with trendingScore for events with accelerating activity across multiple markets.