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

# Pagination

> How to iterate large collections — policies, rules, logs, keys — with skip/limit and the SDK helpers.

Agnes uses **skip / limit** offset pagination on every list endpoint.
The SDKs wrap this transparently with iterators; if you call the API
directly, follow the conventions on this page.

## The wire format

List responses share a common envelope:

```json theme={null}
{
  "items": [ /* ... */ ],
  "total": 142,
  "skip": 0,
  "limit": 50
}
```

| Field   | Meaning                                                       |
| ------- | ------------------------------------------------------------- |
| `items` | The page of results.                                          |
| `total` | Total matching records (across all pages).                    |
| `skip`  | Number of records skipped before the first item on this page. |
| `limit` | Maximum number of items per page.                             |

To fetch the next page, send `skip = previous_skip + previous_limit`.

```http theme={null}
GET /api/v1/policies/?skip=0&limit=50
GET /api/v1/policies/?skip=50&limit=50
GET /api/v1/policies/?skip=100&limit=50
```

When `skip + len(items) >= total`, you're done.

## Default and maximum limits

| Endpoint family                                                    | Default `limit` | Max `limit` |
| ------------------------------------------------------------------ | --------------- | ----------- |
| Policies, YARA rules, YARA policies, SDP policies, safety policies | 50              | 200         |
| API keys                                                           | 50              | 200         |
| Analyzer logs (`/api/v1/analyzer-logs/search`)                     | 100             | 1,000       |
| Tenants (admin only)                                               | 50              | 200         |

If you exceed the maximum, the API returns
[`validation_error`](/errors/validation_error) with a 422.

## Filtering

Many list endpoints support a `search` query parameter that does
case-insensitive substring matching against the resource's `name` (or
the most relevant field). Combine with `skip` / `limit`:

```http theme={null}
GET /api/v1/yara-rules/?search=injection&skip=0&limit=50
```

The auto-generated [API reference](/api-reference/overview) page for
each endpoint enumerates the supported filters.

## SDK helpers

Both SDKs hide the `skip` / `limit` math behind iterators.

### Python

```python theme={null}
# Iterate every item, transparently fetching pages
for policy in agnes.policies.list():
    print(policy["name"])

# Or page-at-a-time
for page in agnes.policies.list().pages():
    print(page.total, page.skip, len(page.items))

# With a search filter
for rule in agnes.yara.rules.list(search="injection"):
    print(rule["name"])
```

`.pages()` is useful if you want to know `total` up front (e.g. to
render a progress bar) or you want to break the iteration after the
first interesting page.

### TypeScript

```ts theme={null}
for await (const policy of agnes.policies.list()) {
  console.log(policy.name);
}

// Page-at-a-time
for await (const page of agnes.policies.list().pages()) {
  console.log(page.total, page.skip, page.items.length);
}
```

The async iterator backs each page with a single HTTP call; you do
not need to manage offsets yourself.

## Stable ordering

List endpoints sort by `created_at DESC, id DESC` by default. For most
collections this is "newest first", which keeps the first page useful
in dashboards. If you need a different order (e.g. alphabetical for
policies), the dashboard's policy list does the sort client-side; the
API does not currently expose a sort parameter.

The `is_default` flag promotes the default policy to the top of the
list returned by `GET /api/v1/policies/`. SDKs preserve that order.

## Performance notes

* **Keep `limit` reasonable.** For UI lists, `50` is a good default;
  going past `200` on policies / rules will rarely render usefully.
* **Stream analyzer logs.** For exports of more than a few thousand
  events, prefer the `POST /api/v1/analyzer-logs/search` endpoint
  rather than `GET /api/v1/analyzer-logs/events_summary`. The search
  endpoint is paginated and tuned for high-volume reads.
* **Don't poll for new pages on a hot loop.** If you want
  near-real-time analysis log updates, use the analyzer log
  Elasticsearch index via the search endpoint with a
  `created_at >= now-1m` filter.

## Next

* [Rate limits](/api-reference/rate-limits) — list endpoints share
  the per-tenant budget.
* [Errors → `validation_error`](/errors/validation_error) — what
  happens when `limit` exceeds the cap.
* [API reference overview](/api-reference/overview) — auto-generated
  endpoint pages.