View as Markdown

Time seeking

/locate turns a commit time into a cursor with an index seek (no scan). Combine it with /read to read a time window.

H="authorization: Bearer $CAPLESS_API_KEY"

curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" \
  -d '{"committedAt":"2026-10-29T00:00:00Z","mode":"at_or_after"}'
# → {"cursor":"cur_…","batchId":"019a…","committedAt":"2026-10-29T00:00:00.412Z","snapshotCursor":"cur_…"}

/read with afterCursor: cursor therefore starts with the selected batch. If no batch qualifies, batchId and committedAt are null, and cursor is the head (at_or_after) or the origin (at_or_before).

#Reading a window

Everything committed on 29 October (UTC):

FROM=$(curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" -d '{"committedAt":"2026-10-29T00:00:00Z"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).cursor')
TO=$(curl -s https://api.capless.sh/v1/streams/web.events/locate -H "$H" -d '{"committedAt":"2026-10-30T00:00:00Z"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).cursor')
curl -s https://api.capless.sh/v1/streams/web.events/read -H "$H" -d "{\"afterCursor\":\"$FROM\",\"beforeCursor\":\"$TO\"}"

#Commit time vs. event time

• committedAt is the ingestion commit time encoded in the batch ID (the first 48 bits of the UUIDv7), not a timestamp inside your records.
• It is approximate but monotonic: bursts within one millisecond and clock regressions reuse the previous millisecond.
• To filter on a time inside your records, use CEL, e.g. timestamp(entry.timestamp) > timestamp("2026-10-29T00:00:00Z"). Seek by commit time first to bound the scan.
• In filter/map, committedAt is available as a CEL timestamp: committedAt >= timestamp("2026-10-29T00:00:00Z").

All timestamps are UTC ISO 8601 with millisecond precision.