> ## 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. # filterPredictionEvents > Filters prediction events using optional text, IDs, and ranking criteria. filterPredictionEvents query reference: arguments and response fields. > [!NOTE] > > At least for the time being, this endpoint requires a Growth or Enterprise plan. [Learn more](https://dashboard.codex.io/dashboard/billing?utm_source=codex\&utm_medium=docs\&utm_campaign=billing). ## GraphQL ``` type Query { # Requires a Growth or Enterprise plan. filterPredictionEvents( filters: PredictionEventFilters phrase: String eventIds: [String!] excludeEventIds: [String!] rankings: [PredictionEventRanking!] marketSort: PredictionEventMarketSort limit: Int offset: Int ): PredictionEventFilterConnection } enum PredictionProtocol { POLYMARKET KALSHI } enum PredictionEventStatus { OPEN SUSPENDED RESOLVED CANCELLED PENDING } type SearchPredictionEvent { id: String! venueEventId: String! venueSeriesId: String exchangeAddress: String networkId: Int protocol: PredictionProtocol! status: PredictionEventStatus! slug: String! question: String! description: String tags: [String!]! imageThumbUrl: String venueUrl: String! createdAt: Int! opensAt: Int! closesAt: Int resolvesAt: Int resolvedAt: Int } type PredictionResolution { result: String source: String } type PredictionSubSubcategory { name: String! slug: String! } type PredictionSubcategory { name: String! slug: String! subcategories: [PredictionSubSubcategory!] } type PredictionCategory { name: String! slug: String! subcategories: [PredictionSubcategory!] } enum PredictionMetadataType { SPORTS } type SportsTeam { abbreviation: String! altAbbreviations: [String!] name: String league: String logo: String alias: String color: String providerId: Int isHome: Boolean } enum SportsTimezone { UTC } type KalshiSportsTickerComponents { rawTicker: String! seriesPrefix: String! seriesSport: String teamTailRaw: String homeAbbreviation: String awayAbbreviation: String } type DecomposedVenueTicker { kalshiSports: KalshiSportsTickerComponents } type SportsEventEnrichedMetadata { league: String teams: [SportsTeam!] gameStartDate: String gameStartTime: String gameStartTimeSeconds: Int gameStartTimezone: SportsTimezone decomposedVenueTicker: DecomposedVenueTicker } type PredictionEventEnrichedMetadata { metadataType: PredictionMetadataType! sports: SportsEventEnrichedMetadata } type PredictionEvent { id: String! protocol: PredictionProtocol! venueEventId: String! venueSeriesId: String status: PredictionEventStatus! question: String! url: String! rulesPrimary: String! rulesSecondary: String tags: [String!]! opensAt: Int! closesAt: Int resolvesAt: Int resolvedAt: Int resolution: PredictionResolution imageLargeUrl: String imageThumbUrl: String imageSmallUrl: String createdAt: Int! updatedAt: Int! networkId: Int marketIds: [String!] categories: [PredictionCategory!] enrichedMetadata: PredictionEventEnrichedMetadata } enum PredictionMarketRole { MONEYLINE MONEYLINE_OUTCOME ENTRANT SPREAD TOTAL PROP THRESHOLD_BUCKET DATE_BUCKET EXOTIC OTHER } type PredictionEventTopMarket { marketId: String! label: String! outcome0Label: String! outcome1Label: String! outcome0BidCT: String! outcome0BidUSD: String! outcome0AskCT: String! outcome0AskUSD: String! outcome1BidCT: String! outcome1BidUSD: String! outcome1AskCT: String! outcome1AskUSD: String! volumeCT1d: String! volumeUSD1d: String! volumeCT1w: String! volumeUSD1w: String! volumeCTAll: String! volumeUSDAll: String! thumbUrl: String role: PredictionMarketRole suggestedLabel: String countryCode: String } type PredictionEventFilterResultMarket { id: String! label: String } type PredictionEventMarketCounts { open: Int! suspended: Int! resolved: Int! cancelled: Int! pending: Int! } enum PredictionEventShape { SPORTS_MATCH SPORTS_SERIES SPORTS_CHAMPIONSHIP ESPORTS_MATCH AWARDS_SHOW ELECTION PRICE_THRESHOLD DATE FED_DECISION BINARY WEATHER MULTI_SELECT OTHER } type PredictionEventFilterResult { id: String! timestamp: Int! lastTransactionAt: Int! event: SearchPredictionEvent! predictionEvent: PredictionEvent protocol: PredictionProtocol! status: PredictionEventStatus! createdAt: Int! age: Int expectedLifespan: Int opensAt: Int! closesAt: Int resolvesAt: Int resolvedAt: Int topMarkets: [PredictionEventTopMarket!]! markets: [PredictionEventFilterResultMarket!]! marketCount: Int! marketCounts: PredictionEventMarketCounts categories: [String!]! resolutionSource: String relatedEventIds: [String!]! trendingScore5m: Float trendingScore1h: Float trendingScore4h: Float trendingScore12h: Float trendingScore24h: Float trendingScore1w: Float relevanceScore5m: Float relevanceScore1h: Float relevanceScore4h: Float relevanceScore12h: Float relevanceScore24h: Float relevanceScore1w: Float liquidityUsd: String liquidityCT: String liquidityChange5m: Float liquidityChange1h: Float liquidityChange4h: Float liquidityChange12h: Float liquidityChange24h: Float liquidityChange1w: Float openInterestUsd: String openInterestCT: String openInterestChange5m: Float openInterestChange1h: Float openInterestChange4h: Float openInterestChange12h: Float openInterestChange24h: Float openInterestChange1w: Float volumeUsd5m: String volumeUsd1h: String volumeUsd4h: String volumeUsd12h: String volumeUsd24h: String volumeUsd1w: String volumeUsdAll: String volumeCTAll: String venueVolumeUsd: String venueVolumeCT: String volumeChange5m: Float volumeChange1h: Float volumeChange4h: Float volumeChange12h: Float volumeChange24h: Float volumeChange1w: Float trades5m: Int trades1h: Int trades4h: Int trades12h: Int trades24h: Int trades1w: Int tradesChange5m: Float tradesChange1h: Float tradesChange4h: Float tradesChange12h: Float tradesChange24h: Float tradesChange1w: Float uniqueTraders5m: Int uniqueTraders1h: Int uniqueTraders4h: Int uniqueTraders12h: Int uniqueTraders24h: Int uniqueTraders1w: Int uniqueTradersChange5m: Float uniqueTradersChange1h: Float uniqueTradersChange4h: Float uniqueTradersChange12h: Float uniqueTradersChange24h: Float uniqueTradersChange1w: Float eventShape: PredictionEventShape } type PredictionEventFilterConnection { count: Int! page: Int! results: [PredictionEventFilterResult!]! } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input PredictionEventFilters { protocol: [PredictionProtocol!] status: [PredictionEventStatus!] categories: [String!] excludeCategories: [String!] hasCategories: Boolean resolutionSource: [String!] venueSeriesId: [String!] timestamp: NumberFilter lastTransactionAt: NumberFilter createdAt: NumberFilter age: NumberFilter expectedLifespan: NumberFilter opensAt: NumberFilter closesAt: NumberFilter resolvesAt: NumberFilter resolvedAt: NumberFilter marketCount: NumberFilter trendingScore5m: NumberFilter trendingScore1h: NumberFilter trendingScore4h: NumberFilter trendingScore12h: NumberFilter trendingScore24h: NumberFilter trendingScore1w: NumberFilter relevanceScore5m: NumberFilter relevanceScore1h: NumberFilter relevanceScore4h: NumberFilter relevanceScore12h: NumberFilter relevanceScore24h: NumberFilter relevanceScore1w: NumberFilter liquidityUsd: NumberFilter liquidityCT: NumberFilter liquidityChange5m: NumberFilter liquidityChange1h: NumberFilter liquidityChange4h: NumberFilter liquidityChange12h: NumberFilter liquidityChange24h: NumberFilter liquidityChange1w: NumberFilter openInterestUsd: NumberFilter openInterestCT: NumberFilter openInterestChange5m: NumberFilter openInterestChange1h: NumberFilter openInterestChange4h: NumberFilter openInterestChange12h: NumberFilter openInterestChange24h: NumberFilter openInterestChange1w: NumberFilter volumeUsd5m: NumberFilter volumeUsd1h: NumberFilter volumeUsd4h: NumberFilter volumeUsd12h: NumberFilter volumeUsd24h: NumberFilter volumeUsd1w: NumberFilter volumeUsdAll: NumberFilter volumeCTAll: NumberFilter venueVolumeUsd: NumberFilter venueVolumeCT: NumberFilter volumeChange5m: NumberFilter volumeChange1h: NumberFilter volumeChange4h: NumberFilter volumeChange12h: NumberFilter volumeChange24h: NumberFilter volumeChange1w: NumberFilter trades5m: NumberFilter trades1h: NumberFilter trades4h: NumberFilter trades12h: NumberFilter trades24h: NumberFilter trades1w: NumberFilter tradesChange5m: NumberFilter tradesChange1h: NumberFilter tradesChange4h: NumberFilter tradesChange12h: NumberFilter tradesChange24h: NumberFilter tradesChange1w: NumberFilter uniqueTraders5m: NumberFilter uniqueTraders1h: NumberFilter uniqueTraders4h: NumberFilter uniqueTraders12h: NumberFilter uniqueTraders24h: NumberFilter uniqueTraders1w: NumberFilter uniqueTradersChange5m: NumberFilter uniqueTradersChange1h: NumberFilter uniqueTradersChange4h: NumberFilter uniqueTradersChange12h: NumberFilter uniqueTradersChange24h: NumberFilter uniqueTradersChange1w: NumberFilter } enum PredictionEventRankingAttribute { timestamp lastTransactionAt createdAt age expectedLifespan opensAt closesAt resolvesAt resolvedAt marketCount trendingScore5m trendingScore1h trendingScore4h trendingScore12h trendingScore24h trendingScore1w relevanceScore5m relevanceScore1h relevanceScore4h relevanceScore12h relevanceScore24h relevanceScore1w liquidityUsd liquidityCT liquidityChange5m liquidityChange1h liquidityChange4h liquidityChange12h liquidityChange24h liquidityChange1w openInterestUsd openInterestCT openInterestChange5m openInterestChange1h openInterestChange4h openInterestChange12h openInterestChange24h openInterestChange1w volumeUsd5m volumeUsd1h volumeUsd4h volumeUsd12h volumeUsd24h volumeUsd1w volumeUsdAll volumeCTAll venueVolumeUsd venueVolumeCT volumeChange5m volumeChange1h volumeChange4h volumeChange12h volumeChange24h volumeChange1w trades5m trades1h trades4h trades12h trades24h trades1w tradesChange5m tradesChange1h tradesChange4h tradesChange12h tradesChange24h tradesChange1w uniqueTraders5m uniqueTraders1h uniqueTraders4h uniqueTraders12h uniqueTraders24h uniqueTraders1w uniqueTradersChange5m uniqueTradersChange1h uniqueTradersChange4h uniqueTradersChange12h uniqueTradersChange24h uniqueTradersChange1w phraseScore } enum RankingDirection { ASC DESC } input PredictionEventRanking { attribute: PredictionEventRankingAttribute! direction: RankingDirection } ``` ## Example: Top events by 24h volume [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { 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 } } } ``` ```json Example Response (truncated) theme={null} { "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 ```graphql theme={null} { 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 ```graphql theme={null} { 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 ```graphql theme={null} { 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 * Default 100 results per request; `limit` accepts up to 200. * 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`](https://docs.codex.io/api-reference/queries/filterpredictionevents) to find high-level topics, then drill into individual markets with [`filterPredictionMarkets`](https://docs.codex.io/api-reference/queries/filterpredictionmarkets). ### Event Status Values See the [`PredictionEventStatus`](https://docs.codex.io/api-reference/enums/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 > [accordion] How do I find events with many betting options? > > 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. > [accordion] How do I track event momentum? > > Use the change metrics like `volumeChange24h`, `liquidityChange24h`, and `uniqueTradersChange24h`. Positive values indicate growth. Combine with `trendingScore` for events with accelerating activity across multiple markets. ### Related Recipes * [Discover Prediction Markets](https://docs.codex.io/recipes/predictions/discover-markets.md): Build filterable, sortable discovery pages for events and markets * [Prediction Event Dashboard](https://docs.codex.io/recipes/predictions/event-dashboard.md): Build a full event detail page with markets, charts, and trades This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.