Candlesticks

cURL

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": 568,
  "params": {
    "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
    "interval": "1h",
    "start_time": "1769910300",
    "end_time": "1770034843377"
  },
  "pagination": { "limit": 10, "offset": 0 },
  "formatter_config": { "format_type": "raw" }
}'

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 568,
        "params": {
            "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
            "interval": "1h",
            "start_time": "1769910300",
            "end_time": "1770034843377",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())

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: 568,
      params: {
        token_id:
          "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        interval: "1h",
        start_time: "1769910300",
        end_time: "1770034843377",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "interval": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "token_id": "<string>",
        "timestamp": "<string>",
        "open": "<string>",
        "high": "<string>",
        "low": "<string>",
        "close": "<string>",
        "volume": "<string>"
      }
    ]
  },
  "request_id": "<string>"
}

POST

api

semantic

retrieve

parameterized

cURL

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": 568,
  "params": {
    "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
    "interval": "1h",
    "start_time": "1769910300",
    "end_time": "1770034843377"
  },
  "pagination": { "limit": 10, "offset": 0 },
  "formatter_config": { "format_type": "raw" }
}'

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "agent_id": 568,
        "params": {
            "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
            "interval": "1h",
            "start_time": "1769910300",
            "end_time": "1770034843377",
        },
        "pagination": {"limit": 10, "offset": 0},
        "formatter_config": {"format_type": "raw"},
    },
)

print(response.json())

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: 568,
      params: {
        token_id:
          "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        interval: "1h",
        start_time: "1769910300",
        end_time: "1770034843377",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "interval": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "token_id": "<string>",
        "timestamp": "<string>",
        "open": "<string>",
        "high": "<string>",
        "low": "<string>",
        "close": "<string>",
        "volume": "<string>"
      }
    ]
  },
  "request_id": "<string>"
}

Platform: Polymarket
Endpoint: POST /v2/semantic/retrieve/parameterized
Authentication: Bearer token

Query parameters

All requests use agent_id 568 (Candlesticks). 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 (`side_a_token_id` / `side_b_token_id`).
`interval`	String	Candle interval: `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`.
`start_time`	String	Unix timestamp in seconds for the range start (for example, `"1769910300"`).
`end_time`	String	Unix timestamp in seconds for the range end (for example, `"1770034843377"`).

Example Request

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": 568,
  "params": {
    "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
    "interval": "1h",
    "start_time": "1769910300",
    "end_time": "1770034843377"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 568,
    "params": {
        "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        "interval": "1h",
        "start_time": "1769910300",
        "end_time": "1770034843377"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())

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": 568,
  "params": {
    "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
    "interval": "1h",
    "start_time": "1769910300",
    "end_time": "1770034843377"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();

Example Response

{
  "timestamp": "",
  "params": {
    "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
    "interval": "1h",
    "start_time": "1769910300",
    "end_time": "1770034843377"
  },
  "data": {
    "results": [
      {
        "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        "timestamp": "2026-04-10T18:00:00Z",
        "open": "0.5600",
        "high": "0.5850",
        "low": "0.5520",
        "close": "0.5800",
        "volume": "42310.55"
      },
      {
        "token_id": "85953619064670985626771564660881103494957821937504170459975285010511861618293",
        "timestamp": "2026-04-10T17:00:00Z",
        "open": "0.5450",
        "high": "0.5620",
        "low": "0.5400",
        "close": "0.5600",
        "volume": "31880.20"
      }
    ]
  }
}

Response fields

Field	Type	Description
`token_id`	String	Token ID
`timestamp`	String (ISO 8601)	Candle start time
`open`	String (Decimal)	Opening price
`high`	String (Decimal)	Highest price
`low`	String (Decimal)	Lowest price
`close`	String (Decimal)	Closing price
`volume`	String (Decimal)	Volume during candle (USD)

Notes

Use shorter intervals (e.g., 1m, 5m) intervals for intraday / pre-game analysis

Always match the interval with an appropriate start_time and end_time range. Requesting more data than the max range for a given interval will produce empty or incomplete results.

Use offset in the pagination object when retrieving large datasets to iterate through results efficiently.

Authorizations

Authorization

string

header

required

Your Falcon API key from the dashboard

Body

application/json

params

object

required

Filter parameters. All values must be strings.

Hide child attributes

params.token_id

string

required

Token ID of the market outcome. Find this on the Polymarket Markets endpoint (side_a_token_id / side_b_token_id).

params.interval

enum<string>

required

Candle interval (for example, "1h" for hourly candles).

Available options:

1m,

5m,

15m,

1h,

4h,

1d

params.start_time

string

Unix timestamp in seconds for the range start, as a string (for example, "1769910300").

params.end_time

string

Unix timestamp in seconds for the range end, as a string (for example, "1770034843377").

agent_id

enum<integer>

default:568

Candlesticks agent ID.

Available options:

568

pagination

object

Hide child attributes

pagination.limit

integer

default:10

Maximum number of records returned per request.

Required range: 1 <= x <= 200

pagination.offset

integer

default:0

Number of records to skip before returning results.

Required range: x >= 0

formatter_config

object

Hide child attributes

formatter_config.format_type

enum<string>

default:raw

Output format. Use "raw" for structured JSON.

Available options:

raw

Response

Success

timestamp

string

read-only

params

object

read-only

Hide child attributes

params.token_id

string

read-only

params.interval

string

read-only

params.start_time

string

read-only

params.end_time

string

read-only

pagination

object

read-only

Hide child attributes

pagination.limit

integer

read-only

pagination.offset

integer

read-only

pagination.has_more

boolean

read-only

data

object

read-only

Hide child attributes

data.results

object[]

read-only

Hide child attributes

data.results.token_id

string

read-only

Token ID

data.results.timestamp

string

read-only

Candle start time (ISO 8601)

data.results.open

string

read-only

Opening price

data.results.high

string

read-only

Highest price

data.results.low

string

read-only

Lowest price

data.results.close

string

read-only

Closing price

data.results.volume

string

read-only

Volume during candle (USD)

request_id

string

read-only

Overview

Composite workflows

Polymarket

Kalshi

Social Intelligence

Query parameters

Example Request

Example Response

Response fields

Notes

Authorizations

Body

Response

​Query parameters

​Example Request

​Example Response

​Response fields

​Notes

Authorizations

Body

Response

Query parameters

Example Request

Example Response

Response fields

Notes