# Time seeking

`/locate` turns a commit time into a cursor with an index seek (no scan). Combine it with [`/read`](https://capless.sh/docs/reading.md) to read a time window.

```sh
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_…"}
```

| `mode` | Returns |
|---|---|
| `at_or_after` (default) | the boundary right before the first batch committed at or after `committedAt` |
| `at_or_before` | the boundary before the last batch committed at or before `committedAt` |

`/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):

```sh
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.