> ## 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. # filterPredictionMarkets > Filters prediction markets using optional text, IDs, event constraints, and ranking criteria. Codex API GraphQL query reference. > [!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. filterPredictionMarkets( filters: PredictionMarketFilters phrase: String marketIds: [String!] excludeMarketIds: [String!] eventIds: [String!] excludeEventIds: [String!] rankings: [PredictionMarketRanking!] limit: Int offset: Int ): PredictionMarketFilterConnection } enum PredictionMarketRole { MONEYLINE MONEYLINE_OUTCOME ENTRANT SPREAD TOTAL PROP THRESHOLD_BUCKET DATE_BUCKET EXOTIC OTHER } enum PredictionMarketSegmentType { STAT PERIOD NONE } enum PredictionMarketStatType { POINTS REBOUNDS ASSISTS THREES STEALS BLOCKS TURNOVERS FOULS DOUBLE_DOUBLE TRIPLE_DOUBLE FIRST_INNING_RUNS } type PredictionMarketSegment { type: PredictionMarketSegmentType! period: String stat: PredictionMarketStatType groupingKey: String! numberValue: Float } enum PredictionMarketEntrantKind { PERSON PLAYER TEAM COUNTRY COMPANY TOPIC TV_SHOW MOVIE SONG ALBUM OTHER } type PredictionMarketEntrant { kind: PredictionMarketEntrantKind! displayName: String! imageUrl: String countryCode: String } enum PredictionMarketLadderMetric { PRICE STOCK_PRICE FDV COMMODITY TEMPERATURE RATE_CHANGE_BPS ROTTEN_TOMATOES BOX_OFFICE TWEETS FOLLOWERS SUBSCRIBERS VIEWS LIKES POSTS OTHER } enum PredictionMarketLadderOperator { ABOVE BELOW EXACTLY BETWEEN } type PredictionMarketThresholdBucket { metric: PredictionMarketLadderMetric! operator: PredictionMarketLadderOperator! numericValue: Float lowerBound: Float upperBound: Float } enum PredictionMarketDateOperator { BEFORE AFTER ON BETWEEN } type PredictionMarketDateBucket { operator: PredictionMarketDateOperator! unixTimestamp: Int lowerTimestamp: Int upperTimestamp: Int } type PredictionMarketClassification { role: PredictionMarketRole! sortKey: Int segment: PredictionMarketSegment! entrant: PredictionMarketEntrant thresholdBucket: PredictionMarketThresholdBucket dateBucket: PredictionMarketDateBucket rawSubtype: String } enum PredictionProtocol { POLYMARKET KALSHI } enum PredictionEventStatus { OPEN SUSPENDED RESOLVED CANCELLED PENDING } type SearchPredictionMarket { id: String! eventId: String! protocol: PredictionProtocol! venueMarketId: String! venueMarketSlug: String exchangeAddress: String networkId: Int venueEventId: String label: String suggestedLabel: String question: String collateral: String! createdAt: Int! opensAt: Int closesAt: Int resolvesAt: Int resolvedAt: Int status: PredictionEventStatus! tags: [String!] imageThumbUrl: String } 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 SportsMarketEnrichedMetadata { sportsMarketType: String league: String teams: [SportsTeam!] gameStartDate: String gameStartTime: String gameStartTimeSeconds: Int gameStartTimezone: SportsTimezone } type PredictionMarketEnrichedMetadata { metadataType: PredictionMetadataType! sports: SportsMarketEnrichedMetadata } type PredictionMarket { id: String! protocol: PredictionProtocol! venueMarketId: String! venueMarketSlug: String eventId: String venueEventId: String question: String label: String suggestedLabel: String eventLabel: String rules: String rules2: String venueOutcomeIds: [String!]! outcomeIds: [String!]! outcomeLabels: [String!] resolution: PredictionResolution imageLargeUrl: String imageThumbUrl: String imageSmallUrl: String createdAt: Int updatedAt: Int opensAt: Int closesAt: Int resolvesAt: Int resolvedAt: Int observedAt: Int! networkId: Int exchangeAddress: String categories: [PredictionCategory!] winningOutcomeId: String enrichedMetadata: PredictionMarketEnrichedMetadata } type PredictionOutcomeFilterResult { id: String! label: String suggestedLabel: String venueOutcomeId: String! isWinner: Boolean tokenAddress: String networkId: Int exchangeAddress: String tags: [String!] bestBidUsd: String bestAskUsd: String spreadUsd: String lastPriceUsd: String bestBidCT: String bestAskCT: String spreadCT: String lastPriceCT: String bestBookBidUsd: String bestBookBidCT: String bestBookAskUsd: String bestBookAskCT: String bookLiquidityUsd: String bookLiquidityCT: String liquidityUsd: String liquidityCT: String twoPercentAskDepthUsd: String twoPercentBidDepthUsd: String twoPercentAskDepthCT: String twoPercentBidDepthCT: String highPriceUsd5m: String highPriceUsd1h: String highPriceUsd4h: String highPriceUsd12h: String highPriceUsd24h: String highPriceUsd1w: String lowPriceUsd5m: String lowPriceUsd1h: String lowPriceUsd4h: String lowPriceUsd12h: String lowPriceUsd24h: String lowPriceUsd1w: String volumeUsd5m: String volumeUsd1h: String volumeUsd4h: String volumeUsd12h: String volumeUsd24h: String volumeUsd1w: String volumeChange5m: Float volumeChange1h: Float volumeChange4h: Float volumeChange12h: Float volumeChange24h: Float volumeChange1w: Float volumeShares5m: String volumeShares1h: String volumeShares4h: String volumeShares12h: String volumeShares24h: String volumeShares1w: String buyVolumeUsd5m: String buyVolumeUsd1h: String buyVolumeUsd4h: String buyVolumeUsd12h: String buyVolumeUsd24h: String buyVolumeUsd1w: String sellVolumeUsd5m: String sellVolumeUsd1h: String sellVolumeUsd4h: String sellVolumeUsd12h: String sellVolumeUsd24h: String sellVolumeUsd1w: String trades5m: Int trades1h: Int trades4h: Int trades12h: Int trades24h: Int trades1w: Int buys5m: Int buys1h: Int buys4h: Int buys12h: Int buys24h: Int buys1w: Int sells5m: Int sells1h: Int sells4h: Int sells12h: Int sells24h: Int sells1w: Int tradesChange5m: Float tradesChange1h: Float tradesChange4h: Float tradesChange12h: Float tradesChange24h: Float tradesChange1w: Float priceChange5m: Float priceChange1h: Float priceChange4h: Float priceChange12h: Float priceChange24h: Float priceChange1w: Float priceRange5m: Float priceRange1h: Float priceRange4h: Float priceRange12h: Float priceRange24h: Float priceRange1w: Float } type PredictionMarketFilterResult { id: String! timestamp: Int! lastTransactionAt: Int! age: Int expectedLifespan: Int eventLabel: String classification: PredictionMarketClassification market: SearchPredictionMarket! predictionMarket: PredictionMarket protocol: PredictionProtocol! status: PredictionEventStatus! opensAt: Int! closesAt: Int! resolvesAt: Int! categories: [String!]! resolutionSource: String outcome0: PredictionOutcomeFilterResult! outcome1: PredictionOutcomeFilterResult! winningOutcomeId: 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 competitiveScore5m: Float competitiveScore1h: Float competitiveScore4h: Float competitiveScore12h: Float competitiveScore24h: Float competitiveScore1w: 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 avgTradeSizeUsd5m: String avgTradeSizeUsd1h: String avgTradeSizeUsd4h: String avgTradeSizeUsd12h: String avgTradeSizeUsd24h: String avgTradeSizeUsd1w: String 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 priceCompetitiveness: Float volumeImbalance24h: Float liquidityAsymmetry: Float impliedProbabilitySum: Float maxPriceRange5m: Float maxPriceRange1h: Float maxPriceRange4h: Float maxPriceRange12h: Float maxPriceRange24h: Float maxPriceRange1w: Float } type PredictionMarketFilterConnection { count: Int! page: Int! results: [PredictionMarketFilterResult!]! } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input PredictionOutcomeFilters { bestBidUsd: NumberFilter bestAskUsd: NumberFilter spreadUsd: NumberFilter lastPriceUsd: NumberFilter trades5m: NumberFilter trades1h: NumberFilter trades4h: NumberFilter trades12h: NumberFilter trades24h: NumberFilter trades1w: NumberFilter priceChange5m: NumberFilter priceChange1h: NumberFilter priceChange4h: NumberFilter priceChange12h: NumberFilter priceChange24h: NumberFilter priceChange1w: NumberFilter } input PredictionMarketFilters { protocol: [PredictionProtocol!] status: [PredictionEventStatus!] categories: [String!] excludeCategories: [String!] hasCategories: Boolean resolutionSource: [String!] timestamp: NumberFilter lastTransactionAt: NumberFilter age: NumberFilter createdAt: NumberFilter expectedLifespan: NumberFilter opensAt: NumberFilter closesAt: NumberFilter resolvesAt: 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 competitiveScore5m: NumberFilter competitiveScore1h: NumberFilter competitiveScore4h: NumberFilter competitiveScore12h: NumberFilter competitiveScore24h: NumberFilter competitiveScore1w: 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 avgTradeSizeUsd5m: NumberFilter avgTradeSizeUsd1h: NumberFilter avgTradeSizeUsd4h: NumberFilter avgTradeSizeUsd12h: NumberFilter avgTradeSizeUsd24h: NumberFilter avgTradeSizeUsd1w: 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 priceCompetitiveness: NumberFilter volumeImbalance24h: NumberFilter liquidityAsymmetry: NumberFilter impliedProbabilitySum: NumberFilter maxPriceRange5m: NumberFilter maxPriceRange1h: NumberFilter maxPriceRange4h: NumberFilter maxPriceRange12h: NumberFilter maxPriceRange24h: NumberFilter maxPriceRange1w: NumberFilter outcome0: PredictionOutcomeFilters outcome1: PredictionOutcomeFilters outcomeOr: PredictionOutcomeFilters } enum PredictionMarketRankingAttribute { timestamp lastTransactionAt age createdAt expectedLifespan opensAt closesAt resolvesAt trendingScore5m trendingScore1h trendingScore4h trendingScore12h trendingScore24h trendingScore1w relevanceScore5m relevanceScore1h relevanceScore4h relevanceScore12h relevanceScore24h relevanceScore1w competitiveScore5m competitiveScore1h competitiveScore4h competitiveScore12h competitiveScore24h competitiveScore1w 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 avgTradeSizeUsd5m avgTradeSizeUsd1h avgTradeSizeUsd4h avgTradeSizeUsd12h avgTradeSizeUsd24h avgTradeSizeUsd1w tradesChange5m tradesChange1h tradesChange4h tradesChange12h tradesChange24h tradesChange1w uniqueTraders5m uniqueTraders1h uniqueTraders4h uniqueTraders12h uniqueTraders24h uniqueTraders1w uniqueTradersChange5m uniqueTradersChange1h uniqueTradersChange4h uniqueTradersChange12h uniqueTradersChange24h uniqueTradersChange1w priceCompetitiveness volumeImbalance24h liquidityAsymmetry impliedProbabilitySum maxPriceRange5m maxPriceRange1h maxPriceRange4h maxPriceRange12h maxPriceRange24h maxPriceRange1w phraseScore } enum PredictionOutcomeIndex { outcome0 outcome1 } enum PredictionOutcomeRankingAttribute { bestBidUsd bestAskUsd spreadUsd lastPriceUsd bestBidCT bestAskCT spreadCT lastPriceCT liquidityUsd liquidityCT twoPercentAskDepthUsd twoPercentBidDepthUsd twoPercentAskDepthCT twoPercentBidDepthCT highPriceUsd5m highPriceUsd1h highPriceUsd4h highPriceUsd12h highPriceUsd24h highPriceUsd1w lowPriceUsd5m lowPriceUsd1h lowPriceUsd4h lowPriceUsd12h lowPriceUsd24h lowPriceUsd1w volumeUsd5m volumeUsd1h volumeUsd4h volumeUsd12h volumeUsd24h volumeUsd1w volumeChange5m volumeChange1h volumeChange4h volumeChange12h volumeChange24h volumeChange1w volumeShares5m volumeShares1h volumeShares4h volumeShares12h volumeShares24h volumeShares1w buyVolumeUsd5m buyVolumeUsd1h buyVolumeUsd4h buyVolumeUsd12h buyVolumeUsd24h buyVolumeUsd1w sellVolumeUsd5m sellVolumeUsd1h sellVolumeUsd4h sellVolumeUsd12h sellVolumeUsd24h sellVolumeUsd1w trades5m trades1h trades4h trades12h trades24h trades1w buys5m buys1h buys4h buys12h buys24h buys1w sells5m sells1h sells4h sells12h sells24h sells1w tradesChange5m tradesChange1h tradesChange4h tradesChange12h tradesChange24h tradesChange1w priceChange5m priceChange1h priceChange4h priceChange12h priceChange24h priceChange1w priceRange5m priceRange1h priceRange4h priceRange12h priceRange24h priceRange1w } enum RankingDirection { ASC DESC } input PredictionMarketRanking { attribute: PredictionMarketRankingAttribute outcome: PredictionOutcomeIndex outcomeAttribute: PredictionOutcomeRankingAttribute direction: RankingDirection } ``` ## Example: Top markets by 24h volume [Test this query in the Explorer →](https://docs.codex.io/explore.md) ```graphql theme={null} { filterPredictionMarkets( rankings: [ { attribute: volumeUsd24h, direction: DESC } ] limit: 10 ) { count page results { id eventLabel protocol status categories market { question label protocol status collateral networkId opensAt closesAt } outcome0 { label lastPriceUsd liquidityUsd } outcome1 { label lastPriceUsd liquidityUsd } liquidityUsd volumeUsd24h trades24h uniqueTraders24h trendingScore24h } } } ``` ```json Example Response (truncated) theme={null} { "data": { "filterPredictionMarkets": { "count": 10, "page": 0, "results": [ { "id": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137", "eventLabel": "Fed decision in March?", "protocol": "POLYMARKET", "status": "OPEN", "categories": [ "economy", "finance", "politics", "sports", "fed" ], "market": { "question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?", "label": "25+ bps increase", "protocol": "POLYMARKET", "status": "OPEN", "collateral": "{\"type\":\"token\",\"tokenAddress\":\"0x2791bca1f2de4661ed88a30c99a7a9449aa84174\",\"networkId\":137}", "networkId": 137, "opensAt": 1761764467, "closesAt": 1773792000 }, "outcome0": { "label": "Yes", "lastPriceUsd": "0.001", "liquidityUsd": "6324844" }, "outcome1": { "label": "No", "lastPriceUsd": "0.999019", "liquidityUsd": "6329715" }, "liquidityUsd": "12654559", "volumeUsd24h": "8800270", "trades24h": 1079, "uniqueTraders24h": 646, "trendingScore24h": 0.34541965892500454 } // ... 9 more results ] } } } ``` ## Example: Search markets by text ```graphql theme={null} { filterPredictionMarkets( phrase: "Champions League" filters: { status: OPEN } rankings: [ { attribute: volumeUsd24h, direction: DESC } ] limit: 5 ) { count results { eventLabel market { question opensAt closesAt } status categories liquidityUsd volumeUsd24h trendingScore24h } } } ``` ## Example: Filter by category and status ```graphql theme={null} { filterPredictionMarkets( filters: { categories: ["sports", "soccer"] status: OPEN liquidityUsd: { gt: 100000 } } rankings: [ { attribute: trendingScore24h, direction: DESC } ] limit: 10 ) { count results { eventLabel market { question } categories liquidityUsd volumeUsd24h trendingScore24h outcome0 { label lastPriceUsd } outcome1 { label lastPriceUsd } } } } ``` ## Example: Filter by time range and liquidity ```graphql theme={null} { filterPredictionMarkets( filters: { protocol: POLYMARKET closesAt: { gte: 1773000000, lte: 1774000000 } liquidityUsd: { gt: 50000 } } rankings: [ { attribute: uniqueTraders24h, direction: DESC } ] limit: 20 ) { count results { id eventLabel protocol market { question closesAt } liquidityUsd volumeUsd24h uniqueTraders24h trades24h } } } ``` ### Usage Guidelines * Default 100 results per request; `limit` accepts up to 200. * Use `trendingScore24h` or `volumeUsd24h` rankings for discovering active markets * Apply quality filters like minimum liquidity (`liquidityUsd: { gt: 10000 }`) to focus on liquid markets * Use `phrase` parameter to search by market question, event label, or category * Filter by `status: OPEN` to exclude resolved/closed markets * Use `categories` filter to narrow down to specific topics (e.g., "sports", "politics", "crypto") * Combine multiple time windows (5m, 1h, 4h, 12h, 24h, 1w) to analyze market trends over different periods ### Market 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 market with 10x volume growth scores higher than a large market with flat volume) * **relevanceScore** - Measures what "matters" - based on absolute size and capital at stake, with no growth multipliers (large, established markets rank high even if quiet) * **competitiveScore** - Measures genuine uncertainty - higher when prices are near 50%, trading is balanced on both sides, and there's active price discovery ### Troubleshooting Tips > [accordion] What's the difference between volumeUsd24h and volumeUsdAll? > > `volumeUsd24h` shows trading volume in the last 24 hours, while `volumeUsdAll` shows total lifetime volume for the market. For trending markets, use 24h metrics. For market maturity analysis, compare `volumeUsdAll` with time-based volumes. > [accordion] Why are some outcome labels null? > > Some markets use generic Yes/No outcomes without custom labels. Check both `outcome0.label` and `outcome1.label` - if null, treat them as Yes/No or reference the market question for context. > [accordion] How do I track market momentum? > > Use the change metrics like `volumeChange24h`, `liquidityChange24h`, and `uniqueTradersChange24h`. Positive values indicate growth. Combine with `trendingScore` for markets with accelerating activity. ### 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): Use market pricing to populate an event detail page * [Prediction Charts](https://docs.codex.io/recipes/predictions/charts.md): Render outcome probability charts and multi-market comparisons This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.