# Pagination and inclusion

> Follow returned page URLs to read a whole list.

Every list is a page: `object: "list"`, a `data` array and `nextPageUrl`. The same shape is used
for a list response, for an engram's `claims`, and for a Consolidate result's `extractedClaims`.

* `nextPageUrl: null` means there are no more pages.
* A page can be short, or even empty, and still have a `nextPageUrl`. Keep following it until it
  is `null`.
* On an engram, `claimCount` is the total number of claims; `claims.data` holds only this page.

## Reading a Workspace list

Make the first request with your filters and inclusion settings:

```bash
curl --fail-with-body -sS --get "https://api.augenta.ai/v1/engrams" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  --data-urlencode "workspace=$AUGENTA_WORKSPACE_ID" \
  --data-urlencode "include=claims" \
  --data-urlencode "strength[gte]=0.5" \
  --data-urlencode "limit=100" > engrams.json
```

Follow the returned relative URL unchanged. It keeps the Workspace, filters, limit and inclusion
settings of the first request, so don't add or change parameters on it.

```bash
NEXT_PAGE_URL=$(jq -r '.nextPageUrl // empty' engrams.json)
if [ -n "$NEXT_PAGE_URL" ]; then
  curl --fail-with-body -sS "https://api.augenta.ai$NEXT_PAGE_URL" \
    -H "Authorization: AugentaKey $AUGENTA_API_KEY" > engrams-next.json
fi
```

Follow an engram's `claims.nextPageUrl`, or a Workspace Consolidate result's
`extractedClaims.nextPageUrl`, the same way. Access is checked again on every page.

| Error                | Meaning                                                      | What to do                          |
| -------------------- | ------------------------------------------------------------ | ----------------------------------- |
| `409 cursor_stale`   | The Workspace's memory changed while you were reading.       | Start again from the first request. |
| `400 invalid_cursor` | The page URL was edited, or used with a different selection. | Start again from the first request. |

## One-shot output

Consolidate without `workspace` returns bounded lists with `nextPageUrl: null`. Their `truncated`
flag is `true` when items were left out. These results have no browsing continuation: nothing
was stored, so there is no next page to fetch. Use a Workspace when you need to read or recall the
memory later.

## Inclusion and limits

* `include=claims` on an engram list loads the first page of each engram's claims.
* One-shot Consolidate's `include` defaults to `["claims", "extractedClaims"]`; send a subset, or
  `[]`, for less output. Workspace Consolidate accepts only `"extractedClaims"`, its default.
* `limit` and `claims_limit` default to 100 and accept 1–500, as does `engrams_limit` on one-shot
  Consolidate. When engrams carry their claims, a page can hold fewer engrams than `limit` so the
  response stays bounded.
* Page URLs keep these settings; a page request accepts no new ones.

Event lists follow the same `nextPageUrl` rule. Once it is `null`, save the response's `since`
value to poll for later events; see [Events](https://augenta.pages.dev/docs/events.md).

## Administration lists

Organization, Workspace, membership and API-key lists use the same shape. Follow their page URLs
with the same person's credentials. Their `limit` defaults to 50 and accepts 1–200. Access is
checked again on each page, and changing the active organization or the selection invalidates a
page URL. `include=members` loads the first page of members on an organization or Workspace.
