Skip to main content

Work with time-series windows

Many HeliumGeek endpoints expose historical data. Almost all of them accept min_time and max_time query parameters so you can control the observation window. This guide explains how the filters work and how to format timestamps correctly.

Time window parameters​

ParameterRequiredDescription
min_timeNoISO-8601 lower bound for the window. Defaults to the time of the request (new Date()). If you omit it, most time-series calls return either an empty list or only records newer than the implicit max_time.
max_timeNoISO-8601 upper bound. Defaults to the time of the request.

Because both defaults resolve to “now,” you almost always want to provide at least one of them. A typical pattern is to supply only min_time (for example, 24 hours ago) and let max_time default to the current timestamp.

Timestamp format​

Provide timestamps in full ISO-8601 format, including a timezone designator. We recommend UTC with a trailing Z:

2024-03-01T00:00:00Z

If you omit the timezone, the server assumes its own local timezone, which can shift the window unexpectedly. To avoid surprises, always include the offset (Z for UTC or +/-hh:mm).

Example​

Fetch the last 24 hours of radio heartbeats:

curl "https://heliumgeek.com/v0/radios/11abc/heartbeats?min_time=2024-03-17T00:00:00Z&max_time=2024-03-18T00:00:00Z" \
  -H "x-api-key: <your api key>"

The bounds follow the rule min_time ≤ record < max_time. In the example above, records from 2024-03-17T00:00:00Z up to (but not including) 2024-03-18T00:00:00Z are returned. Combine the window with limit/cursor pagination to page through larger ranges.

Period-based records​

Many endpoints return aggregates that include both a start and end timestamp (for example, reward epochs with startPeriod and endPeriod). HeliumGeek evaluates time filters against the end of the period. As long as endPeriod satisfies the window (min_time ≤ endPeriod < max_time), the entire record is included.

For mobile rewards this means the full reward is attributed to the date the Oracle closed the epoch, even if the work that earned it happened earlier. If you query min_time=2024-03-01T00:00:00Z&max_time=2024-03-02T00:00:00Z, only rewards whose endPeriod falls on March 1st are returned.

Keep this behavior in mind when reconciling data with on-device timestamps—period-based records behave more like “posted on” dates than “started on” dates.

Bucketing and aggregation​

Some endpoints expose a bucket parameter (hour, day, or month). When you supply a bucket:

  • Results are grouped by the chosen interval between min_time and max_time.
  • The server still respects the window you define—bucketed statistics outside that range are omitted.

Refer to the endpoint documentation for the exact buckets supported. When in doubt, start with UTC-hour buckets and adjust based on the granularity you need.

Tips​

  • Always send timestamps in UTC unless you have a specific reason not to.
  • Keep windows narrow when exploring interactively (e.g., one day) and widen them gradually if you need more data.
  • If you rerun historical jobs, re-use the exact min_time/max_time values to guarantee deterministic results.
  • Pair time filters with pagination to capture large intervals without hitting rate limits.

Need a refresher on pagination? Head back to the cursor guide.