---
title: "Lists · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/lists
updated: 2026-10-20
licence: "All rights reserved"
---

# Lists

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> Page through long lists with cursors, cap every page, and let clients filter and sort with plain, documented parameters that never change meaning.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/lists`.

## Required

- [Page lists with cursors](https://agentwranglers.se/playbook/api-design/lists/cursor-pagination): Return every list that can grow past one page in pages, and point to the next page with an opaque cursor, not a page number.
- [Cap the page size](https://agentwranglers.se/playbook/api-design/lists/page-size-limit): Set a default page size and a maximum. Clamp or reject anything above the maximum.
- [Return empty lists as empty](https://agentwranglers.se/playbook/api-design/lists/empty-lists): Answer an empty result with 200 and an empty array. Never answer 404 or `null` for a list with nothing in it.

## Recommended

- [Filter with plain parameters](https://agentwranglers.se/playbook/api-design/lists/filtering): Let clients filter lists by named query parameters, and document each one with its type.
- [Sort in a stable order](https://agentwranglers.se/playbook/api-design/lists/sorting): Sort every list in a documented, stable order, and let clients choose from a fixed set of sort keys.

- Previous: [Errors](https://agentwranglers.se/playbook/api-design/errors)
- Next: [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)
- [All chapters](https://agentwranglers.se/playbook/api-design)