Sign in
latestOpenAPI 3.0.32026-08-101461131.1 MB

ad6f143e43aa

futures:aggregates

Aggregates

Get aggregates for a contract in a given time range.

get/futures/v1/aggs/{ticker}

Path parameters

tickerstring required

The futures contract identifier, including the base symbol and contract expiration (e.g., GCJ5 for the April 2025 gold contract).

Query parameters

resolutionstring

The size of each aggregate candle, specified as a number followed by a unit: sec, min, hour, session, week, month, quarter, or year.

Each unit has a maximum multiplier. For instance, minute candles go up to 59min; after that, use 1hour. Requesting an unsupported size returns a 400 Bad Request.

window_startstring

Filter by the start time of each candle. Accepts a YYYY-MM-DD date or a nanosecond Unix timestamp. The value is snapped to the start of the matching candle interval. When omitted, the API returns the most recent candles up to the limit.

Session candles are timestamped at the start of the session, not the trading date they settle on. A futures session opens the evening before it settles, so window_start falls on the day before session_end_date. To pull the session that settles on a given date, set window_start to the day before. For example, window_start=2025-08-05 returns the session that settles on 2025-08-06. Week, month, quarter, and year candles follow the same rule: window_start is the first day of the period and session_end_date is the last trading date in it.

Add a comparison suffix to filter a range: window_start.gte (greater than or equal to), window_start.gt (greater than), window_start.lte (less than or equal to), or window_start.lt (less than).

Examples:

Most recent minute candles: /v1/aggs/ESU5?resolution=1min&limit=5

Session settling 2025-08-06 (pass its start date, 2025-08-05): /v1/aggs/ESU5?resolution=1session&window_start=2025-08-05

Date range: /v1/aggs/ESU5?resolution=1session&window_start.gte=2025-07-01&window_start.lte=2025-07-31

After a timestamp: /v1/aggs/ESU5?resolution=1sec&window_start.gt=1751409877000000000&limit=1000

limitinteger

The number of results to return per page (default=1000, maximum=50000, minimum=1).

window_start.gtestring

Range by window_start.

window_start.gtstring

Range by window_start.

window_start.ltestring

Range by window_start.

window_start.ltstring

Range by window_start.

sort'window_start.asc' | 'window_start.desc'
Example:window_start.desc

Sort results by field and direction using dotted notation (e.g., 'ticker.asc', 'name.desc').

Response

A list of aggregates.

next_urlstring

If present, the URL to the next page of results.

statusstring required

The status of the response.