> ## 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 Price Jumps > Detect significant price jumps on a Polymarket market by scanning candlestick data bucketed at a chosen resolution. Returns all candle-to-candle moves exceeding the configured threshold, sorted by magnitude. **Platform:** Polymarket\ **Endpoint:** `POST /v2/semantic/retrieve/parameterized`\ **Authentication:** Bearer token ## Query parameters All requests use `agent_id` `596` (Price Jumps). Set filters inside `params` in the playground — all values must be strings. | Parameter | Type | Description | | - | - | - | | `token_id` | String | Token ID of the market outcome. Get this from [Polymarket Markets](/docs/market-data/polymarket-markets) (`side_a_token_id` / `side_b_token_id`). | | `resolution` | String | Candle bucket size: `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`. | | `min_change_pct` | String | Minimum absolute percent price change to qualify as a jump (for example, `"10"`). | | `lookback_hours` | String | Hours to scan back from now (for example, `"24"`). | ## 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": 596, "params": { "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "resolution": "15m", "min_change_pct": "10", "lookback_hours": "24" }, "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": 596, "params": { "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "resolution": "15m", "min_change_pct": "10", "lookback_hours": "24" }, "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": 596, "params": { "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "resolution": "15m", "min_change_pct": "10", "lookback_hours": "24" }, "pagination": { "limit": 10, "offset": 0 }, "formatter_config": { "format_type": "raw" } }) }); const data = await response.json(); ``` ## Example Response ```json theme={null} { "timestamp": "", "params": { "lookback_hours": "24", "min_change_pct": "10", "resolution": "15m", "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297" }, "pagination": { "limit": 10, "offset": 0, "has_more": false }, "data": { "results": [ { "change_pct": "-16.67", "condition_id": "0xbcacd5a055f5a9ced6f69f122216c073dd6987d08253fc07bbcc168fa5b81d55", "direction": "down", "jump_time": "2026-04-06T02:00:00Z", "outcome": "Yes", "price_after": "0.1500", "price_before": "0.1800", "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "trade_count": 28, "volume": "7350.07" }, { "change_pct": "14.29", "condition_id": "0xbcacd5a055f5a9ced6f69f122216c073dd6987d08253fc07bbcc168fa5b81d55", "direction": "up", "jump_time": "2026-04-05T19:30:00Z", "outcome": "Yes", "price_after": "0.1600", "price_before": "0.1400", "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "trade_count": 3, "volume": "264.35" } ] }, "request_id": "" } ``` ## Response fields Each object in `data.results` describes one qualifying candle-to-candle move. | Field | Type | Description | | - | - | - | | `jump_time` | String (ISO 8601) | Timestamp of the candle where the jump occurred | | `condition_id` | String | Hex condition ID of the market | | `token_id` | String | Token ID of the outcome | | `outcome` | String | Outcome label | | `price_before` | String (Decimal) | Price at the start of the candle | | `price_after` | String (Decimal) | Price at the end of the candle | | `change_pct` | String (Decimal) | Percentage change (negative = price dropped) | | `direction` | String | `up` or `down` | | `volume` | String (Decimal) | Volume during the candle | | `trade_count` | Integer | Number of trades during the candle | ## OpenAPI ````yaml /api-reference/polymarket-price-jumps.openapi.json POST /api/v2/semantic/retrieve/parameterized openapi: 3.1.0 info: title: Falcon API — Price Jumps 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: Price Jumps description: >- Detect significant price jumps on a Polymarket market by scanning candlestick data at a chosen resolution. operationId: polymarketPriceJumps requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolymarketPriceJumpsRequest' examples: default: summary: 15m jumps over the last 24 hours value: agent_id: 596 params: token_id: >- 99787107393065498256888522570939526464960671564345515510320748534859284179297 resolution: 15m min_change_pct: '10' lookback_hours: '24' pagination: limit: 10 offset: 0 formatter_config: format_type: raw responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PolymarketPriceJumpsResponse' '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": 596, "params": { "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "resolution": "15m", "min_change_pct": "10", "lookback_hours": "24" }, "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": 596, "params": { "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297", "resolution": "15m", "min_change_pct": "10", "lookback_hours": "24", }, "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: 596, params: { token_id: "99787107393065498256888522570939526464960671564345515510320748534859284179297", resolution: "15m", min_change_pct: "10", lookback_hours: "24", }, pagination: { limit: 10, offset: 0 }, formatter_config: { format_type: "raw" }, }), } ); const data = await response.json(); components: schemas: PolymarketPriceJumpsRequest: type: object required: - params properties: agent_id: type: integer enum: - 596 default: 596 x-default: 596 description: Price Jumps agent ID. params: $ref: '#/components/schemas/PolymarketPriceJumpsParams' pagination: $ref: '#/components/schemas/PolymarketPriceJumpsPagination' formatter_config: $ref: '#/components/schemas/PolymarketPriceJumpsFormatterConfig' PolymarketPriceJumpsResponse: type: object readOnly: true properties: timestamp: type: string readOnly: true params: $ref: '#/components/schemas/PolymarketPriceJumpsResponseParams' pagination: type: object readOnly: true properties: limit: type: integer readOnly: true offset: type: integer readOnly: true has_more: type: boolean readOnly: true data: type: object readOnly: true properties: results: type: array readOnly: true items: type: object readOnly: true additionalProperties: true request_id: type: string readOnly: true PolymarketPriceJumpsParams: type: object description: Filter parameters. All values must be strings. additionalProperties: false required: - token_id - resolution - min_change_pct - lookback_hours properties: token_id: type: string default: >- 99787107393065498256888522570939526464960671564345515510320748534859284179297 description: >- Token ID of the market outcome. Get this from Polymarket Markets (`side_a_token_id` / `side_b_token_id`). resolution: type: string enum: - 1m - 5m - 15m - 1h - 4h - 1d default: 15m description: Candle bucket size (for example, "15m"). min_change_pct: type: string default: '10' description: >- Minimum absolute percent price change to qualify as a jump (for example, "10"). lookback_hours: type: string default: '24' description: Hours to scan back from now (for example, "24"). PolymarketPriceJumpsPagination: 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. PolymarketPriceJumpsFormatterConfig: type: object properties: format_type: type: string enum: - raw default: raw description: Output format. Use "raw" for structured JSON. PolymarketPriceJumpsResponseParams: type: object readOnly: true properties: token_id: type: string readOnly: true resolution: type: string readOnly: true min_change_pct: type: string readOnly: true lookback_hours: type: string readOnly: true 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.