> ## Documentation Index > Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Polymarket Markets > Retrieve Polymarket market listings with filtering by condition ID, slug prefix, volume, or resolution status. **Platform:** Polymarket\ **Endpoint:** `POST /v2/semantic/retrieve/parameterized`\ **Authentication:** Bearer token **For sport markets, use slug prefixes:** **-`nba-` → all NBA markets** **-`nfl-` → all NFL markets** **-`epl-` → all EPL markets** **-`mlb-` → all MLB markets** **-`nhl-` → all NHL markets** ## Query parameters All requests use `agent_id` `574` (Polymarket Markets). Set filters inside `params` in the playground — all values must be strings. | Parameter | Type | Description | | - | - | - | | `condition_id` | String | Hex condition ID for an exact market lookup. | | `market_slug` | String | Slug or slug prefix (for example, `"nba-"` for all NBA markets). | | `min_volume` | String | Minimum traded volume in USD (for example, `"10000"`). | | `closed` | String | `"True"` for resolved markets, `"False"` for open. Omit for both. | | `end_date_min` | String | Earliest end date: Unix timestamp in seconds. | | `end_date_max` | String | Latest end date: Unix timestamp in seconds. | ## Example Request ```bash cURL theme={null} curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 574, "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' ``` ```python Python theme={null} import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 574, "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } } ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "agent_id": 574, "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }) }); const data = await response.json(); ``` ## Example Response ```json theme={null} { "timestamp": "", "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": { "limit": 20, "offset": 0, "has_more": true }, "data": { "results": [ { "condition_id": "0xabc123def456...", "question": "Cavaliers vs. Celtics", "slug": "nba-cle-bos-2026-04-11", "end_date": "2026-04-12T00:00:00Z", "volume": "523890.44", "liquidity": "842190.55", "closed": false, "side_a_token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293", "side_b_token_id": "98765432109876543210", "outcome_a": "Cavaliers", "outcome_b": "Celtics", "current_price_a": "0.4200", "current_price_b": "0.5800" } ] } } ``` ## Response fields | Field | Type | Description | | - | - | - | | `condition_id` | String | Market condition ID | | `question` | String | Market question | | `slug` | String | Market slug | | `end_date` | String (ISO 8601) | Market resolution date | | `volume` | String (Decimal) | Total traded volume (USD) | | `liquidity` | String (Decimal) | Current liquidity | | `closed` | Boolean | Whether market is resolved | | `side_a_token_id` | String | Token ID for outcome A (needed for candles, orderbook, and price jumps) | | `side_b_token_id` | String | Token ID for outcome B | | `outcome_a` | String | Label for outcome A | | `outcome_b` | String | Label for outcome B | | `current_price_a` | String (Decimal) | Current price for outcome A | | `current_price_b` | String (Decimal) | Current price for outcome B | ## Notes > [!TIP] > > Use this to get `side_a_token_id` / `side_b_token_id` needed by Price Jumps, Candlesticks, and Orderbook > [!TIP] > > Filter with `closed: "False"` to only see active markets > [!TIP] > > Combine slug prefix with `min_volume` to find liquid sport makets ## OpenAPI ````yaml /api-reference/polymarket-markets.openapi.json POST /api/v2/semantic/retrieve/parameterized openapi: 3.1.0 info: title: Falcon API — Polymarket Markets version: 1.0.0 servers: - url: https://narrative.agent.heisenberg.so description: Production security: - bearerAuth: [] paths: /api/v2/semantic/retrieve/parameterized: post: tags: - Polymarket summary: Polymarket Markets description: >- Retrieve Polymarket market listings with filtering by condition ID, slug prefix, volume, or resolution status. operationId: polymarketMarkets requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolymarketMarketsRequest' examples: default: summary: NBA markets with volume filter value: agent_id: 574 params: market_slug: nba- min_volume: '10000' closed: 'False' end_date_min: '1600000000' end_date_max: '2200000000' pagination: limit: 10 offset: 0 formatter_config: format_type: raw responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PolymarketMarketsResponse' '400': description: Bad request — check params '401': description: Unauthorized — check your Bearer token x-codeSamples: - lang: curl label: cURL source: |- curl --request POST \ --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": 574, "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }' - lang: python label: Python source: |- import requests response = requests.post( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={ "agent_id": 574, "params": { "market_slug": "nba-", "min_volume": "10000", "closed": "False", "end_date_min": "1600000000", "end_date_max": "2200000000" }, "pagination": {"limit": 10, "offset": 0}, "formatter_config": {"format_type": "raw"}, }, ) print(response.json()) - lang: javascript label: JavaScript source: |- const response = await fetch( "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", { method: "POST", headers: { Authorization: "Bearer YOUR_TOKEN", "Content-Type": "application/json", }, body: JSON.stringify({ agent_id: 574, params: { market_slug: "nba-", min_volume: "10000", closed: "False", end_date_min: "1600000000", end_date_max: "2200000000", }, pagination: { limit: 10, offset: 0 }, formatter_config: { format_type: "raw" }, }), } ); const data = await response.json(); components: schemas: PolymarketMarketsRequest: type: object properties: agent_id: type: integer enum: - 574 default: 574 x-default: 574 description: Polymarket Markets agent ID. params: $ref: '#/components/schemas/PolymarketMarketsParams' pagination: $ref: '#/components/schemas/PolymarketMarketsPagination' formatter_config: $ref: '#/components/schemas/PolymarketMarketsFormatterConfig' PolymarketMarketsResponse: type: object readOnly: true properties: timestamp: type: string readOnly: true params: $ref: '#/components/schemas/PolymarketMarketsResponseParams' pagination: type: object properties: limit: type: integer offset: type: integer has_more: type: boolean data: type: object properties: results: type: array items: $ref: '#/components/schemas/PolymarketMarket' request_id: type: string PolymarketMarketsParams: type: object description: Filter parameters. All values must be strings. additionalProperties: false properties: condition_id: type: string description: >- Hex condition ID of a specific market. Use for an exact market lookup. market_slug: type: string description: Slug or slug prefix (for example, "nba-" for all NBA markets). min_volume: type: string description: >- Minimum traded volume in USD, passed as a string (for example, "10000"). closed: type: string enum: - 'True' - 'False' description: >- "True" for resolved markets, "False" for open markets. Omit to return both. end_date_min: type: string description: >- Earliest end date filter: Unix timestamp in seconds, as a string (for example, "1600000000"). end_date_max: type: string description: >- Latest end date filter: Unix timestamp in seconds, as a string (for example, "2200000000"). PolymarketMarketsPagination: type: object properties: limit: type: integer minimum: 1 maximum: 200 default: 10 description: Maximum number of records returned per request. offset: type: integer minimum: 0 default: 0 description: Number of records to skip before returning results. PolymarketMarketsFormatterConfig: type: object properties: format_type: type: string enum: - raw default: raw description: Output format. Use "raw" for structured JSON. PolymarketMarketsResponseParams: type: object readOnly: true properties: condition_id: type: string readOnly: true market_slug: type: string readOnly: true min_volume: type: string readOnly: true closed: type: string readOnly: true end_date_min: type: string readOnly: true end_date_max: type: string readOnly: true PolymarketMarket: type: object readOnly: true properties: condition_id: type: string description: Market condition ID question: type: string description: Market question slug: type: string description: Market slug end_date: type: string description: Market resolution date (ISO 8601) volume: type: string description: Total traded volume (USD) liquidity: type: string description: Current liquidity closed: type: boolean description: Whether market is resolved side_a_token_id: type: string description: >- Token ID for outcome A (needed for candles, orderbook, and price jumps) side_b_token_id: type: string description: Token ID for outcome B outcome_a: type: string description: Label for outcome A outcome_b: type: string description: Label for outcome B current_price_a: type: string description: Current price for outcome A current_price_b: type: string description: Current price for outcome B securitySchemes: bearerAuth: type: http scheme: bearer description: Your Falcon API key from the dashboard ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.