> ## 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. # filterPredictionTraders > Filters prediction traders using optional text, IDs, and ranking criteria. filterPredictionTraders 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). > [!NOTE] > > **Kalshi does not provide trader data**. These endpoints only work with Polymarket data. Kalshi's API does not expose individual trader information due to privacy considerations on their regulated exchange. ## GraphQL ``` type Query { # Requires a Growth or Enterprise plan. filterPredictionTraders( filters: PredictionTraderFilters phrase: String traderIds: [String!] excludeTraderIds: [String!] rankings: [PredictionTraderRanking!] limit: Int offset: Int ): PredictionTraderFilterConnection } enum PredictionProtocol { POLYMARKET KALSHI } type FilterTrader { id: String! venueTraderId: String! protocol: PredictionProtocol! alias: String primaryAddress: String linkedAddresses: [String!] profileImageUrl: String profileUrl: String labels: [String!] } type PredictionTrader { id: String! protocol: PredictionProtocol! venueTraderId: String! alias: String primaryAddress: String linkedAddresses: [String!] profileImageUrl: String profileUrl: String totalTradesCount: Int! totalVolumeUsd: String! totalVolumeCT: String! firstTradeTimestamp: Int! lastTradeTimestamp: Int! biggestWinUsd: String! biggestWinCT: String! biggestLossUsd: String! biggestLossCT: String! allTimeProfitUsd: String! allTimeProfitCT: String! activeMarketsCount: Int! labels: [String!] createdAt: Int! updatedAt: Int! } type PredictionTraderFilterResult { id: String! timestamp: Int! trader: FilterTrader! predictionTrader: PredictionTrader firstTradeTimestamp: Int! lastTradeTimestamp: Int! totalVolumeUsdAll: String! totalVolumeCTAll: String! totalProfitUsdAll: String! totalProfitCTAll: String! totalTradesAll: Int! activeMarketsCount: Int! pnlPerVolumeAll: Float! profitPerTradeUsdAll: String! volumePerTradeUsdAll: String! biggestWinUsd: String! biggestWinCT: String! biggestLossUsd: String! biggestLossCT: String! volumeUsd12h: String! volumeUsd24h: String! volumeUsd1w: String! volumeUsd1m: String! volumeCT12h: String! volumeCT24h: String! volumeCT1w: String! volumeCT1m: String! buyVolumeUsd12h: String! buyVolumeUsd24h: String! buyVolumeUsd1w: String! buyVolumeUsd1m: String! sellVolumeUsd12h: String! sellVolumeUsd24h: String! sellVolumeUsd1w: String! sellVolumeUsd1m: String! volumeChange12h: Float! volumeChange24h: Float! volumeChange1w: Float! volumeChange1m: Float! realizedPnlUsd12h: String! realizedPnlUsd24h: String! realizedPnlUsd1w: String! realizedPnlUsd1m: String! realizedPnlCT12h: String! realizedPnlCT24h: String! realizedPnlCT1w: String! realizedPnlCT1m: String! realizedProfitPercentage12h: Float! realizedProfitPercentage24h: Float! realizedProfitPercentage1w: Float! realizedProfitPercentage1m: Float! realizedPnlChange12h: Float! realizedPnlChange24h: Float! realizedPnlChange1w: Float! realizedPnlChange1m: Float! trades12h: Int! trades24h: Int! trades1w: Int! trades1m: Int! buys12h: Int! buys24h: Int! buys1w: Int! buys1m: Int! sells12h: Int! sells24h: Int! sells1w: Int! sells1m: Int! uniqueMarkets12h: Int! uniqueMarkets24h: Int! uniqueMarkets1w: Int! uniqueMarkets1m: Int! wins12h: Int! wins24h: Int! wins1w: Int! wins1m: Int! losses12h: Int! losses24h: Int! losses1w: Int! losses1m: Int! winRate12h: Float! winRate24h: Float! winRate1w: Float! winRate1m: Float! averageProfitUsdPerTrade12h: String! averageProfitUsdPerTrade24h: String! averageProfitUsdPerTrade1w: String! averageProfitUsdPerTrade1m: String! averageSwapAmountUsd12h: String! averageSwapAmountUsd24h: String! averageSwapAmountUsd1w: String! averageSwapAmountUsd1m: String! heldTokenAcquisitionCostUsd: String! heldTokenAcquisitionCostCT: String! } type PredictionTraderFilterConnection { count: Int! page: Int! results: [PredictionTraderFilterResult!]! } input NumberFilter { gte: Float gt: Float lte: Float lt: Float } input PredictionTraderFilters { protocol: [PredictionProtocol!] labels: [String!] excludeLabels: [String!] timestamp: NumberFilter firstTradeTimestamp: NumberFilter lastTradeTimestamp: NumberFilter totalVolumeUsdAll: NumberFilter totalVolumeCTAll: NumberFilter totalProfitUsdAll: NumberFilter totalProfitCTAll: NumberFilter totalTradesAll: NumberFilter activeMarketsCount: NumberFilter pnlPerVolumeAll: NumberFilter profitPerTradeUsdAll: NumberFilter volumePerTradeUsdAll: NumberFilter biggestWinUsd: NumberFilter biggestWinCT: NumberFilter biggestLossUsd: NumberFilter biggestLossCT: NumberFilter volumeUsd12h: NumberFilter volumeUsd24h: NumberFilter volumeUsd1w: NumberFilter volumeUsd1m: NumberFilter volumeChange12h: NumberFilter volumeChange24h: NumberFilter volumeChange1w: NumberFilter volumeChange1m: NumberFilter realizedPnlUsd12h: NumberFilter realizedPnlUsd24h: NumberFilter realizedPnlUsd1w: NumberFilter realizedPnlUsd1m: NumberFilter realizedProfitPercentage12h: NumberFilter realizedProfitPercentage24h: NumberFilter realizedProfitPercentage1w: NumberFilter realizedProfitPercentage1m: NumberFilter realizedPnlChange12h: NumberFilter realizedPnlChange24h: NumberFilter realizedPnlChange1w: NumberFilter realizedPnlChange1m: NumberFilter trades12h: NumberFilter trades24h: NumberFilter trades1w: NumberFilter trades1m: NumberFilter uniqueMarkets12h: NumberFilter uniqueMarkets24h: NumberFilter uniqueMarkets1w: NumberFilter uniqueMarkets1m: NumberFilter wins12h: NumberFilter wins24h: NumberFilter wins1w: NumberFilter wins1m: NumberFilter losses12h: NumberFilter losses24h: NumberFilter losses1w: NumberFilter losses1m: NumberFilter winRate12h: NumberFilter winRate24h: NumberFilter winRate1w: NumberFilter winRate1m: NumberFilter averageProfitUsdPerTrade12h: NumberFilter averageProfitUsdPerTrade24h: NumberFilter averageProfitUsdPerTrade1w: NumberFilter averageProfitUsdPerTrade1m: NumberFilter averageSwapAmountUsd12h: NumberFilter averageSwapAmountUsd24h: NumberFilter averageSwapAmountUsd1w: NumberFilter averageSwapAmountUsd1m: NumberFilter heldTokenAcquisitionCostUsd: NumberFilter heldTokenAcquisitionCostCT: NumberFilter } enum PredictionTraderRankingAttribute { TIMESTAMP FIRST_TRADE_TIMESTAMP LAST_TRADE_TIMESTAMP TOTAL_VOLUME_USD_ALL TOTAL_VOLUME_CT_ALL TOTAL_PROFIT_USD_ALL TOTAL_PROFIT_CT_ALL TOTAL_TRADES_ALL ACTIVE_MARKETS_COUNT PNL_PER_VOLUME_ALL PROFIT_PER_TRADE_USD_ALL VOLUME_PER_TRADE_USD_ALL BIGGEST_WIN_USD BIGGEST_WIN_CT BIGGEST_LOSS_USD BIGGEST_LOSS_CT VOLUME_USD_12H VOLUME_USD_24H VOLUME_USD_1W VOLUME_USD_1M VOLUME_CHANGE_12H VOLUME_CHANGE_24H VOLUME_CHANGE_1W VOLUME_CHANGE_1M REALIZED_PNL_USD_12H REALIZED_PNL_USD_24H REALIZED_PNL_USD_1W REALIZED_PNL_USD_1M REALIZED_PROFIT_PERCENTAGE_12H REALIZED_PROFIT_PERCENTAGE_24H REALIZED_PROFIT_PERCENTAGE_1W REALIZED_PROFIT_PERCENTAGE_1M REALIZED_PNL_CHANGE_12H REALIZED_PNL_CHANGE_24H REALIZED_PNL_CHANGE_1W REALIZED_PNL_CHANGE_1M TRADES_12H TRADES_24H TRADES_1W TRADES_1M UNIQUE_MARKETS_12H UNIQUE_MARKETS_24H UNIQUE_MARKETS_1W UNIQUE_MARKETS_1M WINS_12H WINS_24H WINS_1W WINS_1M LOSSES_12H LOSSES_24H LOSSES_1W LOSSES_1M WIN_RATE_12H WIN_RATE_24H WIN_RATE_1W WIN_RATE_1M AVERAGE_PROFIT_USD_PER_TRADE_12H AVERAGE_PROFIT_USD_PER_TRADE_24H AVERAGE_PROFIT_USD_PER_TRADE_1W AVERAGE_PROFIT_USD_PER_TRADE_1M AVERAGE_SWAP_AMOUNT_USD_12H AVERAGE_SWAP_AMOUNT_USD_24H AVERAGE_SWAP_AMOUNT_USD_1W AVERAGE_SWAP_AMOUNT_USD_1M HELD_TOKEN_ACQUISITION_COST_USD HELD_TOKEN_ACQUISITION_COST_CT } enum RankingDirection { ASC DESC } input PredictionTraderRanking { attribute: PredictionTraderRankingAttribute! direction: RankingDirection } ``` ## Query Example [Test this query in the Explorer →](https://docs.codex.io/explore.md) Top traders by 24h profit: ```graphql theme={null} { filterPredictionTraders( rankings: [ { attribute: REALIZED_PNL_USD_24H, direction: DESC } ] filters: { trades24h: { gt: 5 } } limit: 10 ) { count page results { id trader { alias primaryAddress profileImageUrl } realizedPnlUsd24h volumeUsd24h trades24h uniqueMarkets24h winRate24h averageProfitUsdPerTrade24h totalVolumeUsdAll totalProfitUsdAll activeMarketsCount } } } ``` ```json Example Response (truncated) theme={null} { "data": { "filterPredictionTraders": { "count": 10, "page": 0, "results": [ { "id": "0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket", "trader": { "alias": "HorizonSplendidView", "primaryAddress": null, "profileImageUrl": null }, "realizedPnlUsd24h": "1959316", "volumeUsd24h": "6060346", "trades24h": 652, "uniqueMarkets24h": 1, "winRate24h": 1, "averageProfitUsdPerTrade24h": "3005.085439", "totalVolumeUsdAll": "21346770", "totalProfitUsdAll": "1710755", "activeMarketsCount": 3 }, // .. 9 more traders ] } } } ``` ### Usage Guidelines * **Trader ID format**: `
:` (e.g., `0x02227b8f5a9636e895607edd3185ed6ee5598ff7:Polymarket`) * Default 100 results per request; `limit` accepts up to 200. * Use time-based metrics (12h, 24h, 1w, 1m) to analyze recent activity and trends * Use all-time metrics (`totalProfitUsdAll`, `totalVolumeUsdAll`) for historical performance * Filter by `activeMarketsCount` to find traders with current positions * Use `phrase` parameter to search by trader alias, address, or venue ID * Combine `winRate` and minimum trade filters to find consistently successful traders * Time windows: 12h (short-term), 24h (daily), 1w (weekly), 1m (monthly), All (lifetime) ### Win Rate Interpretation `winRate` fields show the percentage of profitable closed positions: * **0.0 - 0.3** - Struggling or learning traders * **0.3 - 0.5** - Below-average performance * **0.5 - 0.6** - Average to good performance * **0.6 - 0.8** - Strong performance (above market average) * **0.8 - 1.0** - Exceptional (but verify sample size with `trades` filter) Note: High win rates with low trade counts may be statistical noise. Always filter by minimum trades. ### Troubleshooting Tips > [accordion] What's the difference between totalProfitUsdAll and realizedPnlUsd24h? > > `totalProfitUsdAll` is lifetime cumulative profit across all markets and all time. `realizedPnlUsd24h` is profit earned only in the last 24 hours. Use all-time for track records, use time-windowed for recent performance. > [accordion] How do I identify skilled traders vs lucky ones? > > Look for combination of: (1) High win rate (`winRate1w > 0.6`), (2) Significant volume (`volumeUsd1w > 10000`), (3) Many trades (`trades1w > 50`), (4) Good efficiency (`pnlPerVolumeAll > 0.1`). Single metrics can be misleading. > [accordion] Why is winRate different from realizedProfitPercentage? > > `winRate` counts the percentage of profitable positions (win/loss ratio). `realizedProfitPercentage` measures ROI (profit/capital ratio). You can have 90% win rate but low ROI if your losses are much larger than your wins. > [accordion] What does pnlPerVolumeAll tell me? > > This is profit efficiency - how much profit a trader extracts per dollar of volume traded. A value of 0.05 means $0.05 profit per $1 traded (5% efficiency). Higher values indicate better market timing or edge. Values above 0.1 are exceptional. > [accordion] Why are some trader aliases null? > > Not all traders set public aliases. Use `primaryAddress` as the unique identifier. Some traders prefer to remain pseudonymous. Filter by `isVerified: true` to find traders with platform verification. ### Related Recipes * [Prediction Traders](https://docs.codex.io/recipes/predictions/traders.md): Build trader leaderboards, profiles, and portfolio analytics This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.