Time Range Queries

What you'll learn

Query records that were written within a specific time window.

Time range query

`bash # Convert timestamps to HLC START_HLC=$(python3 -c "import datetime; d=datetime.datetime(2026,7,1); print(int(d.timestamp()*1000)*65536)") END_HLC=$(python3 -c "import datetime; d=datetime.datetime(2026,7,8); print(int(d.timestamp()*1000)*65536)")

curl -s -X POST http://localhost:7475/v1/agents/events/query \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d "{ \"type\": \"time_range\", \"from_hlc\": $START_HLC, \"to_hlc\": $END_HLC, \"limit\": 1000 }" | python3 -m json.tool `

Time range with filter

curl -s -X POST http://localhost:7475/v1/agents/orders/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d "{
    \"type\":     \"time_range\",
    \"from_hlc\": $START_HLC,
    \"to_hlc\":   $END_HLC,
    \"limit\":    1000,
    \"filter\":   {\"field\": \"status\", \"op\": \"eq\", \"value\": \"paid\"}
  }" | python3 -m json.tool

Common billing period patterns

`python import datetime

def billing_period_hlc(year: int, month: int): """Returns (from_hlc, to_hlc) for a calendar month.""" start = datetime.datetime(year, month, 1) if month == 12: end = datetime.datetime(year + 1, 1, 1) else: end = datetime.datetime(year, month + 1, 1) return ( int(start.timestamp() * 1000) * 65536, int(end.timestamp() * 1000) * 65536 - 1 )

from_hlc, to_hlc = billing_period_hlc(2026, 7) `

Challenge

Using an orders agent, query all orders from the past 24 hours. Then count them with a count query using the same time range filter.

---