Reading Records in Depth
Every read path: by hash, latest N, scan with pagination, time travel, chain_head, count.
What you'll learn
- ✓GET /v1/agents/:id/records/:hash — O(1) hash lookup
- ✓type: latest — newest N records
- ✓type: scan + order: desc + after_hlc cursor pagination
- ✓type: as_of — time travel to any past HLC
- ✓type: time_range — records within a window
- ✓type: chain_head, type: first, type: count
Write 10 records, note HLC after record 5, use as_of to confirm only 5 are visible at that timestamp.
Interactive Walkthrough
What you'll learn
Every read path: by hash, latest N, scan with pagination, time travel, chain_head, first, count.
Fetch by content_hash (O(1) lookup)
curl -s http://localhost:7475/v1/agents/users/records/<HASH> \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
| python3 -m json.toolLatest N records
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"type": "latest", "limit": 5}' \
| python3 -m json.toolScan with cursor pagination
`bash
# Page 1
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": "scan", "limit": 10}' | python3 -m json.tool
# Page 2 — use last record's ts_hlc as cursor
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": "scan", "limit": 10, "after_hlc": 1751900065536000}' \
| python3 -m json.tool
`
Scan descending (newest-first)
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": "scan", "limit": 10, "order": "desc"}' \
| python3 -m json.toolTime travel — as_of
# All records that existed as of this HLC timestamp
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"type": "as_of", "ts_hlc": 1751900065536000, "limit": 100}' \
| python3 -m json.toolTime range
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": 1751800000000000,
"to_hlc": 1751900000000000,
"limit": 100
}' | python3 -m json.toolchain_head and count
`bash
# Current tip of the strand
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"type": "chain_head"}' | python3 -m json.tool
# Count all records
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{"type": "count"}' | python3 -m json.tool
`
Challenge
Write 10 records, note the HLC after record 5, then use as_of to confirm only 5 records are visible at that timestamp.
---