> ## Documentation Index > Fetch the complete documentation index at: https://docs.struct.to/llms.txt > Use this file to discover all available pages before exploring further. # Get markets > Retrieve a paginated list of markets with filtering, sorting, and optional nested tags/events/metrics ## OpenAPI ````yaml https://api.struct.to/openapi.json get /polymarket/market openapi: 3.1.0 info: title: Polymarket API description: >- RESTful API for querying Polymarket prediction markets data including events, markets, traders, holders, and real-time metrics license: name: '' version: 1.0.0 servers: - url: https://api.struct.to/v1 security: [] paths: /polymarket/market: get: tags: - Market summary: Get markets description: >- Retrieve a paginated list of markets with filtering, sorting, and optional nested tags/events/metrics operationId: list_markets parameters: - name: condition_ids in: query description: Filter by condition ID(s) - comma-separated (max 50) required: false schema: type: string - name: question_ids in: query description: Filter by question ID(s) - comma-separated (max 50) required: false schema: type: string - name: market_ids in: query description: Filter by market ID(s) - comma-separated (max 50) required: false schema: type: string - name: market_slugs in: query description: Filter by market slug(s) - comma-separated (max 50) required: false schema: type: string - name: event_slugs in: query description: Filter by event slug(s) - comma-separated (max 50) required: false schema: type: string - name: position_ids in: query description: Filter by position ID(s) - comma-separated (max 50) required: false schema: type: string - name: search in: query description: Search in title (3-100 characters) required: false schema: type: string - name: status in: query description: 'Filter by status: open, closed, or all (default: all)' required: false schema: $ref: '#/components/schemas/MarketStatus' - name: sort_by in: query description: >- Sort: volume, txns, unique_traders, liquidity, holders, total_daily_rate, end_time, start_time, created_time, relevance required: false schema: $ref: '#/components/schemas/MarketSortBy' - name: sort_dir in: query description: 'Sort direction: asc, desc (default: desc)' required: false schema: $ref: '#/components/schemas/SortDirection' - name: timeframe in: query description: 'Metrics timeframe: 1m, 5m, 30m, 1h, 6h, 24h, 7d, 30d (default: 24h)' required: false schema: $ref: '#/components/schemas/MetricsTimeframe' - name: min_volume in: query description: Minimum total volume USD required: false schema: type: number format: double - name: max_volume in: query description: Maximum total volume USD required: false schema: type: number format: double - name: min_liquidity in: query description: Minimum liquidity USD required: false schema: type: number format: double - name: max_liquidity in: query description: Maximum liquidity USD required: false schema: type: number format: double - name: min_txns in: query description: Minimum transactions in selected timeframe required: false schema: type: integer format: int32 - name: max_txns in: query description: Maximum transactions in selected timeframe required: false schema: type: integer format: int32 - name: min_unique_traders in: query description: Minimum unique traders in selected timeframe required: false schema: type: integer format: int32 - name: max_unique_traders in: query description: Maximum unique traders in selected timeframe required: false schema: type: integer format: int32 - name: min_holders in: query description: Minimum total holders required: false schema: type: integer format: int64 - name: max_holders in: query description: Maximum total holders required: false schema: type: integer format: int64 - name: categories in: query description: Comma-separated category filters (max 50) required: false schema: type: string - name: exclude_categories in: query description: Comma-separated categories to exclude required: false schema: type: string - name: tags in: query description: Filter by tag(s) - comma-separated (max 50) required: false schema: type: string - name: exclude_tags in: query description: Comma-separated tags to exclude required: false schema: type: string - name: start_time in: query description: Filter markets with end_time >= start_time (Unix timestamp) required: false schema: type: integer format: int64 - name: end_time in: query description: Filter markets with end_time <= end_time (Unix timestamp) required: false schema: type: integer format: int64 - name: include_tags in: query description: 'Include tags array (default: true)' required: false schema: type: boolean - name: include_event in: query description: 'Include event object (default: true)' required: false schema: type: boolean - name: include_metrics in: query description: 'Include all timeframe metrics (default: true)' required: false schema: type: boolean - name: limit in: query description: 'Results limit (default: 10, max: 100)' required: false schema: type: integer format: int32 - name: pagination_key in: query description: Cursor-based pagination key required: false schema: type: string - name: has_rewards in: query description: 'Only return markets that have CLOB rewards (default: false)' required: false schema: type: boolean - name: ai in: query description: >- Return truncated response optimized for AI consumers (default: false) required: false schema: type: boolean responses: '200': description: >- List of markets with metadata, outcomes, tags, event, and metrics. Response includes `pagination: { has_more, pagination_key }` for cursor-based pagination. content: application/json: schema: type: array items: $ref: '#/components/schemas/MarketResponse' '400': description: >- Bad request - validation error (search length, array limits, conflicting params) components: schemas: MarketStatus: type: string enum: - open - closed - all MarketSortBy: type: string enum: - volume - txns - unique_traders - liquidity - holders - total_daily_rate - end_time - start_time - created_time - relevance SortDirection: type: string enum: - asc - desc MetricsTimeframe: type: string enum: - 1m - 5m - 30m - 1h - 6h - 24h - 7d - 30d - lifetime MarketResponse: type: object description: >- Formatted market response with structured metrics, tags, outcomes, and event properties: condition_id: type: string description: Condition ID. default: '' id: type: - string - 'null' description: ID. default: null market_slug: type: - string - 'null' description: Market slug. default: null question: type: - string - 'null' description: Question. default: null title: type: - string - 'null' description: Title. default: null description: type: - string - 'null' description: Description. default: null image_url: type: - string - 'null' description: Image URL. default: null oracle: type: - string - 'null' description: Oracle. default: null status: type: string description: Status. default: '' created_time: type: - integer - 'null' format: int64 description: Created time timestamp. default: null start_time: type: - integer - 'null' format: int64 description: Start time timestamp. default: null game_start_time: type: - integer - 'null' format: int64 description: Game start time timestamp. default: null closed_time: type: - integer - 'null' format: int64 description: Closed time timestamp. default: null end_time: type: - integer - 'null' format: int64 description: End time timestamp. default: null accepting_orders: type: - boolean - 'null' description: Accepting orders. default: null uma_resolution_status: type: - string - 'null' description: Uma resolution status. default: null is_neg_risk: type: - boolean - 'null' description: Whether neg risk is true. default: null market_maker_address: type: - string - 'null' description: Market maker address. default: null creator: type: - string - 'null' description: Creator. default: null category: type: - string - 'null' description: Category. default: null volume_usd: type: - number - 'null' format: double description: Volume in USD. default: null liquidity_usd: type: - number - 'null' format: double description: Liquidity in USD. default: null highest_probability: type: - number - 'null' format: double description: Highest probability. default: null total_holders: type: - integer - 'null' format: int64 description: Total holders. default: null total_daily_rate: type: - number - 'null' format: double description: Total daily rate. default: null winning_outcome: oneOf: - type: 'null' - $ref: '#/components/schemas/MarketOutcome' description: Winning outcome. default: null outcomes: type: array items: $ref: '#/components/schemas/MarketOutcome' description: Outcomes. clob_rewards: type: array items: $ref: '#/components/schemas/ClobReward' description: Clob rewards. tags: type: array items: type: string description: Tags. event_slug: type: - string - 'null' description: Event slug. default: null resolution_source: type: - string - 'null' description: Resolution source. default: null metrics: type: object description: >- Per-timeframe metrics keyed by lookback window. Each timeframe key is optional — present only when data exists for that window. properties: 1m: $ref: '#/components/schemas/SimpleTimeframeMetrics' 5m: $ref: '#/components/schemas/SimpleTimeframeMetrics' 30m: $ref: '#/components/schemas/SimpleTimeframeMetrics' 1h: $ref: '#/components/schemas/SimpleTimeframeMetrics' 6h: $ref: '#/components/schemas/SimpleTimeframeMetrics' 24h: $ref: '#/components/schemas/SimpleTimeframeMetrics' 7d: $ref: '#/components/schemas/SimpleTimeframeMetrics' 30d: $ref: '#/components/schemas/SimpleTimeframeMetrics' lifetime: $ref: '#/components/schemas/SimpleTimeframeMetrics' relevance_score: type: - number - 'null' format: double description: Relevance score. default: null MarketOutcome: type: object description: Outcome for market API responses properties: name: type: string description: Name. default: '' price: type: - number - 'null' format: double description: Price. default: null position_id: type: - string - 'null' description: Position ID. default: null outcome_index: type: - integer - 'null' format: int32 description: Outcome index. default: null latest_block: type: - integer - 'null' format: int64 description: Block of the most recent price update for this outcome. default: null latest_confirmed_at: type: - integer - 'null' format: int64 description: Unix-seconds timestamp of the most recent price update. default: null ClobReward: type: object description: CLOB reward (public API format) required: - id - condition_id properties: id: type: string condition_id: type: string asset_address: type: - string - 'null' rewards_amount: type: - number - 'null' format: double rewards_daily_rate: type: - number - 'null' format: double start_date: type: - string - 'null' end_date: type: - string - 'null' rewards_max_spread: type: - number - 'null' format: double rewards_min_size: type: - number - 'null' format: double native_daily_rate: type: - number - 'null' format: double sponsored_daily_rate: type: - number - 'null' format: double total_daily_rate: type: - number - 'null' format: double sponsors_count: type: - integer - 'null' format: int32 SimpleTimeframeMetrics: type: object properties: volume: type: number format: double default: 0 shares_volume: type: number format: double default: 0 builder_usd_volume: type: number format: double default: 0 builder_shares_volume: type: number format: double default: 0 fees: type: number format: double default: 0 builder_fees: type: number format: double default: 0 txns: type: integer format: int32 default: 0 builder_txns: type: integer format: int32 default: 0 unique_traders: type: integer format: int32 default: 0 unique_makers: type: integer format: int32 default: 0 unique_takers: type: integer format: int32 default: 0 unique_builder_traders: type: integer format: int32 default: 0 ````