Pagination

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:

{
  "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.

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 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:

GET /api/v1/yara-rules/?search=injection&skip=0&limit=50

The auto-generated API reference page for each endpoint enumerates the supported filters.

SDK helpers

Both SDKs hide the skip / limit math behind iterators.

Python

# 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

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.

Rate limits — list endpoints share the per-tenant budget.
Errors → validation_error — what happens when limit exceeds the cap.
API reference overview — auto-generated endpoint pages.

Reference

Errors

The wire format

Default and maximum limits

Filtering

SDK helpers

Python

TypeScript

Stable ordering

Performance notes

Next

​The wire format

​Default and maximum limits

​Filtering

​SDK helpers

​Python

​TypeScript

​Stable ordering

​Performance notes

​Next

The wire format

Default and maximum limits

Filtering

SDK helpers

Python

TypeScript

Stable ordering

Performance notes

Next