> ## Documentation Index
> Fetch the complete documentation index at: https://octolens.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination & time windows

> How --limit and --all bound a list, what pagination.nextCursor means in --json output, and the shapes and defaults of --since and --until.

Two flag pairs bound almost every read in the CLI: `--limit` / `--all`
decide *how many* records you get, and `--since` / `--until` decide *which
time range* they come from. Both pairs behave identically on every command
that accepts them — this page states the rules once; the per-command flag
tables live on the command pages.

## `--limit` vs `--all`

Every list command accepts both flags, with one meaning each:

* `--limit N` — the first N items;
* `--all` — the complete result, however many pages that takes;
* **neither** — one server page of 20 items on a cursor-paginated list
  (`octolens mentions list` and friends);
* **both** — a contradiction, refused before any request is made: exit `2`
  with `CONFLICTING_FLAGS`.

```bash theme={null}
octolens mentions list --limit 50 --json
octolens mentions list --all --json
```

The small per-workspace collections — keywords, feeds, tags, members,
notifications — are *bounded*: the API returns them whole, so there is no
cursor to walk. The same two flags still work there and mean the same thing
to you; the CLI applies them as a client-side head of the already-complete
result, and omitting both returns the full collection rather than one page:

```bash theme={null}
octolens keywords list --limit 5
```

## `pagination.nextCursor` in `--json`

Every list's `--json` document carries a `pagination.nextCursor` field:
an opaque string while more records exist beyond what was returned, and
`null` when the listing is complete. Three consequences:

* after `--all`, `nextCursor` is always `null` — the collection was drained;
* on a bounded list it is always `null` — the collection arrived whole, and
  `--limit` was only a client-side head of it;
* a non-null cursor is the signal to re-run with a larger `--limit` (or
  `--all`) if you wanted everything — the CLI walks cursors internally, so
  the value itself matters only to direct callers of the v2 REST API, where
  the cursor parameter lives.

The per-list document shapes, `nextCursor` included, are in the **Returns**
sections of the command pages.

## `--since` / `--until` shapes

Both flags take ISO 8601, in two shapes:

* a **date** — `2026-06-01`;
* a **datetime** — `2026-06-01T09:30:00Z`.

A bare date expands to the *whole day it names*: as `--since` it means the
start of that day, as `--until` the end of it, so
`--since 2026-06-01 --until 2026-06-01` is the full one-day window — the
named day is never silently excluded. A datetime is exact and never
adjusted.

Anything else is refused client-side, before any request: a non-ISO shape or
an impossible calendar date (`2026-02-30`) exits `2` with `INVALID_DATE`
naming the flag and value, and a window whose end precedes its start exits
`2` with `INVALID_WINDOW` — an inverted window cannot match anything, so the
CLI refuses to ask the API and then report the inevitable empty result as if
the data did not exist.

```bash theme={null}
octolens mentions list --since 2026-06-01 --until 2026-06-30
```

## No default window

Mention reads apply **no default time window**: omit both flags and the
range is unbounded — the web app's feed opens on a recent slice, but the CLI
does not copy that default, so `octolens mentions export` with no window is
your entire history. Each bound also works alone: only `--since` leaves the
end open, and only `--until` reaches back to your oldest mention.

The `analytics` group is the one exception, because an aggregation needs a
window to aggregate over: there `--since` and `--until` must be passed
together (only one of the pair exits `2` with `INCOMPLETE_WINDOW`), and
omitting both applies the server's default window — the flag table on
[Analytics & insights](/docs/cli/commands/analytics) states it.

```bash theme={null}
octolens analytics volume --since 2026-06-01 --until 2026-06-30
```