Datasets · Trades

Trade Run Structure

Consecutive same-direction trade run lengths, imbalance, flip rate, and price change on direction flip. The same rows over both transports, under the same names.

Exchanges: binance-futures, okx-perps, hyperliquid-perps · Intervals: 15s 30s 1m 5m 15m 30m 1h 4h 1d · Chart, sample rows and coverage in the catalog

Fields

7 fields, plus time

Every row carries time, the interval's start in milliseconds since the Unix epoch (UTC), and these fields. They are the Parquet columns over REST and the keys of data in a live frame.

Field	Name	Description
`buy_run_max_len`	Max Buy Run Length	Longest consecutive run of buy-side trades
`sell_run_max_len`	Max Sell Run Length	Longest consecutive run of sell-side trades
`buy_run_mean_len`	Mean Buy Run Length	Average length of consecutive buy-side runs
`sell_run_mean_len`	Mean Sell Run Length	Average length of consecutive sell-side runs
`run_imbalance`	Run Imbalance	Normalized difference between the longest buy run and longest sell run
`flip_rate`	Flip Rate	Share of trades whose side flipped versus the previous trade
`price_change_on_flip`	Price Change on Flip	Average absolute price change when trade direction flips

History over REST

Parameters, files and errors for every dataset

One request returns download URLs for the Parquet files that cover your date range: a file per month for older history, a file per day from 2026-08-01. Request them again when they expire.

# Install the Aperiodic CLI into ~/.local/bin
mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/aperiodic-io/cli/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash
export PATH="$HOME/.local/bin:$PATH"

# Free preview — no API key required
aperiodic run_structure --preview \
  --exchange binance-futures \
  --symbol perpetual-BTC-USDT:USDT \
  --interval 5m \
  --timestamp exchange \
  --start-date 2025-05-01 \
  --end-date 2025-05-31 \
  --output-dir ./data && echo "Saved to $PWD/data"

GET/api/v1/data/run_structure

Parameters

Parameter	Values	Meaning
`timestamp`query · required	`exchangetrue`	Timestamp source. 'exchange' uses the exchange-reported timestamp, 'true' uses actual arrival time at our servers.
`interval`query · required	`15s30s1m5m15m30m1h4h1d`	Aggregation time interval for the data. Sub-minute intervals (15s, 30s) require an Institutional plan.
`exchange`query · required	`binance-futuresokx-perpshyperliquid-perps`	Source exchange for the data.
`symbol`query · required	string	Trading pair symbol in the format of Atlas' universal symbology: https://github.com/aperiodic-io/atlas
`start_date`query · required	date	Start date for the data range (YYYY-MM-DD format). A metric series starts on the first day of the raw series it is computed from (see /metadata/raw); raw trades and quotes start binance-futures from 2020-01-01, okx-perps from 2019-09-01, hyperliquid-perps from 2025-01-01. Earlier days return no files. How far back you can go depends on the plan: 5 years on Pro, full history on Prime, Prime + Raw and Institutional. An earlier start_date than the plan reaches returns 403.
`end_date`query · required	date	End date for the data range (YYYY-MM-DD format). Must be greater than or equal to start_date.

Responses

200 response

{
  "files": [
    {
      "year": 2026,
      "month": 6,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-06.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 7,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-07.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 8,
      "day": 1,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-01.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 8,
      "day": 2,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-02.parquet?X-Amz-Expires=300&..."
    }
  ]
}

Status	Meaning
`200`	Successful response with download URLs for every existing file covering the range from the series' published start — one per month before 2026-08-01, one per day from 2026-08-01 onwards
`400`	Bad request - missing or invalid parameters
`401`	Unauthorized - missing or invalid API key
`403`	Forbidden - the subscription does not cover this request
`404`	Unknown dataset
`500`	Server error - failed to resolve the series start or generate download URLs

Try it

Prefilled with the shared DEMO-KEY and a free preview slice — send the request to see live data, no account required.

timestamp*

interval*

exchange*

symbol*

Suggestions shown — any valid value accepted

start_date*

Suggestions shown — any valid value accepted

end_date*

Suggestions shown — any valid value accepted

Authentication

X-API-KEY*

GET

/api/v1/data/preview/run_structure?timestamp=exchange&interval=5m&exchange=binance-futures&symbol=perpetual-BTC-USDT%3AUSDT&start_date=2025-05-01&end_date=2025-05-31

Response will appear here

Live over WebSocket

Connecting, replay and limits for every channel

Subscribe to run_structure.binance-futures.1m, or any exchange and interval below, and each row arrives as its bar closes. After a reconnect, add since to the subscribe to get the bars you missed first (replay).

Exchanges: binance-futures okx-perps hyperliquid-perps
Intervals: 15s 30s 1m 5m 15m 30m 1h 4h 1d

pip install "aperiodic[stream]"

pypi ↗

import os

from aperiodic import stream

for message in stream(
    api_key=os.environ["APERIODIC_API_KEY"],
    dataset="run_structure",
    exchange="binance-futures",
    interval="1m",
    symbols=["perpetual-BTC-USDT:USDT"],  # omit for every symbol on your plan
):
    print(message.channel, message.snapshot, message.data)

Each row

{"channel":"run_structure.binance-futures.1m","data":{"time":…,"buy_run_max_len":…,"sell_run_max_len":…,…}}

Your key is on Live Streams once you are on a plan that streams.

Field

Name

Description

buy_run_max_len

Max Buy Run Length

Longest consecutive run of buy-side trades

sell_run_max_len

Max Sell Run Length

Longest consecutive run of sell-side trades

buy_run_mean_len

Mean Buy Run Length

Average length of consecutive buy-side runs

sell_run_mean_len

Mean Sell Run Length

Average length of consecutive sell-side runs

run_imbalance

Run Imbalance

Normalized difference between the longest buy run and longest sell run

flip_rate

Flip Rate

Share of trades whose side flipped versus the previous trade

price_change_on_flip

Price Change on Flip

Average absolute price change when trade direction flips

# Install the Aperiodic CLI into ~/.local/bin mkdir -p "$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/aperiodic-io/cli/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash export PATH="$HOME/.local/bin:$PATH" # Free preview — no API key required aperiodic run_structure --preview \ --exchange binance-futures \ --symbol perpetual-BTC-USDT:USDT \ --interval 5m \ --timestamp exchange \ --start-date 2025-05-01 \ --end-date 2025-05-31 \ --output-dir ./data && echo "Saved to $PWD/data"

Parameter

Values

Meaning

timestampquery · required

exchangetrue

Timestamp source. 'exchange' uses the exchange-reported timestamp, 'true' uses actual arrival time at our servers.

intervalquery · required

15s30s1m5m15m30m1h4h1d

Aggregation time interval for the data. Sub-minute intervals (15s, 30s) require an Institutional plan.

exchangequery · required

binance-futuresokx-perpshyperliquid-perps

Source exchange for the data.

symbolquery · required

string

Trading pair symbol in the format of Atlas' universal symbology: https://github.com/aperiodic-io/atlas

start_datequery · required

date

Start date for the data range (YYYY-MM-DD format). A metric series starts on the first day of the raw series it is computed from (see /metadata/raw); raw trades and quotes start binance-futures from 2020-01-01, okx-perps from 2019-09-01, hyperliquid-perps from 2025-01-01. Earlier days return no files. How far back you can go depends on the plan: 5 years on Pro, full history on Prime, Prime + Raw and Institutional. An earlier start_date than the plan reaches returns 403.

end_datequery · required

date

End date for the data range (YYYY-MM-DD format). Must be greater than or equal to start_date.

{ "files": [ { "year": 2026, "month": 6, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-06.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 7, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-07.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 8, "day": 1, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-01.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 8, "day": 2, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-02.parquet?X-Amz-Expires=300&..." } ] }

Status

Meaning

200

Successful response with download URLs for every existing file covering the range from the series' published start — one per month before 2026-08-01, one per day from 2026-08-01 onwards

400

Bad request - missing or invalid parameters

401

Unauthorized - missing or invalid API key

403

Forbidden - the subscription does not cover this request

404

Unknown dataset

500

Server error - failed to resolve the series start or generate download URLs

import os from aperiodic import stream for message in stream( api_key=os.environ["APERIODIC_API_KEY"], dataset="run_structure", exchange="binance-futures", interval="1m", symbols=["perpetual-BTC-USDT:USDT"], # omit for every symbol on your plan ): print(message.channel, message.snapshot, message.data)

Trade Run Structure

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket

Trade Run Structure

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket