GET /v1/futures/series
Updated
What does GET /v1/futures/series do?
One futures column for one contract across a time range, at 1-minute (Ultra and pay-per-call), 5-minute, hourly or daily resolution. Returns one column of one contract over a window, as points ordered oldest first. Use it to chart funding, open interest, basis inputs or taker flow over time.
Prices, funding and open interest roll up to the last value of each bucket; volume, trade counts and liquidations are summed; the quality bitmask is ORed, so a bucket is flagged if any minute in it was.
from is clamped to your plan’s history window, the same as spot: futures are kept forever, and a plan reads 2 weeks on Free, 3 months on Pro and pay per call, 1 year on Max and the full archive on Ultra. A request that would return more than 50,000 points keeps the newest and says truncated.
Authentication
API key required. Set $BF to the API base and pass your key in $BLACKFORGE_API_KEY.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
exchange | string | Yes | Futures venue: binance, bitget, bybit, gate, kucoin, mexc, okx. |
symbol | string | Yes | The venue's own contract symbol, as GET /v1/futures/symbols lists it: BTCUSDT (binance, bybit, bitget), BTC-USDT-SWAP (okx), BTC_USDT (gate, mexc), XBTUSDTM (kucoin). |
metric | string | Yes | One plottable futures column key from GET /v1/catalog (`futures.metrics`), e.g. fundingRate, openInterestValue, markPrice, takerBuyQuoteVolume, liqLongNotional. |
from | string | Yes | Range start, ISO 8601. |
to | string | Yes | Range end, ISO 8601. |
interval | string (1m | 5m | 1h | 1d) | Yes | Bucket size. A plan may ask for any interval no finer than its own granularity (Free 1d, Pro 1h, Max 5m, Ultra and pay-per-call 1m). |
Parameter shapes from the live OpenAPI document.
Example request
curl -H "x-api-key: $BLACKFORGE_API_KEY" \
"$BF/v1/futures/series?exchange=binance&symbol=BTCUSDT&metric=openInterestValue&interval=5m&from=2026-11-09T12:56:14Z&to=2026-11-09T13:56:14Z"Example response
{
"metric": "openInterestValue",
"exchange": "binance",
"symbol": "BTCUSDT",
"interval": "5m",
"points": [
"…",
{
"ts": 1794231300000,
"value": 7208928019.377509,
"quality": 0,
"qualityAll": 0
},
{
"ts": 1794231600000,
"value": 7213459977.0513315,
"quality": 0,
"qualityAll": 0
},
{
"ts": 1794231900000,
"value": 7210050410.832772,
"quality": 0,
"qualityAll": 0
},
{
"ts": 1794232200000,
"value": 7227371047.554,
"quality": 0,
"qualityAll": 0
}
]
}Returns
A JSON object with the echoed metric, exchange, symbol and interval, and a points array, oldest first. Each point has ts (epoch milliseconds), value, and the bucket’s quality and qualityAll bitmasks.
Responses and errors
| Status | When |
|---|---|
400 | A required parameter is missing, the metric is unknown or not a number, or the interval is not one of 1m, 5m, 1h, 1d. |
401 | The x-api-key header is missing or not a valid key. |
402 | No key and no x402 payment: the pay-per-call challenge is returned. |
403 | The venue, the interval or the column is not on your plan (liquidation columns are Max and up). |
Columns it returns
Every futures column, its unit, the plan it opens on and the venues that publish it are on the futures data page, with the limits of each venue’s data.