Metrics Data API

Overview

get_metrics() queries Binance UM futures metrics records from DolphinDB. It follows the same style as get_kline() and get_trade(), and supports:

• single or multiple symbols
• date-range filtering
• field projection (fields)
• pagination (limit + offset)

API

get_metrics()

client.get_metrics(
    symbol: str | list[str],
    start_date: str,
    end_date: str,
    fields: str = "*",
    limit: int = 2_000_000,
    offset: int = 0,
) -> pd.DataFrame

Equivalent service call:

client.metrics.get_metrics(...)

Parameters

Parameter	Type	Default	Description
symbol	str | list[str]	required	Contract code(s), e.g. "BTCUSDT" or ["BTCUSDT","ETHUSDT"]
start_date	str	required	Inclusive start date in YYYY-MM-DD
end_date	str	required	Inclusive end date in YYYY-MM-DD
fields	str	"*"	Columns to return, comma-separated
limit	int	2_000_000	Max rows to return
offset	int	0	Pagination offset

Returned Data

Returns a pd.DataFrame. Typical columns in the metrics table:

• trade_date
• symbol
• create_time
• sum_open_interest
• sum_open_interest_value
• count_toptrader_long_short_ratio
• sum_toptrader_long_short_ratio
• count_long_short_ratio
• sum_taker_long_short_vol_ratio
• update_time

If no data matches, an empty DataFrame is returned.

Examples

Single symbol

import zer0data as zd

client = zd.Client()
df = client.get_metrics(
    symbol="BTCUSDT",
    start_date="2026-03-01",
    end_date="2026-03-01",
)
print(df.head())

Multiple symbols and selected fields

df = client.get_metrics(
    symbol=["BTCUSDT", "ETHUSDT"],
    start_date="2026-03-01",
    end_date="2026-03-02",
    fields="symbol,trade_date,create_time,sum_open_interest",
    limit=5000,
    offset=0,
)

Use service directly

svc = zd.MetricsService()
df = svc.get_metrics(
    symbol="ETHUSDT",
    start_date="2026-03-01",
    end_date="2026-03-01",
)

Notes

• Date format must be YYYY-MM-DD.
• Query scope is market="crypto" only.
• For large ranges, prefer explicit fields and smaller page sizes.