# Pagination (/api-reference/pagination)



Zumik list endpoints return an OpenAI-style list envelope. Today every list returns its results in a single, complete page, so there is no cursor to follow. The envelope still carries `has_more` so clients written against it keep working if a list grows large enough to page later.

## The list envelope [#the-list-envelope]

A list response is an object with `object: "list"` and a `data` array:

```json
{
  "object": "list",
  "data": [
    { "id": "art_01jy...", "object": "artifact" }
  ],
  "has_more": false
}
```

<ResponseField name="object" type="string">
  Always `"list"`.
</ResponseField>

<ResponseField name="data" type="array">
  The items. The element shape depends on the endpoint (for example `model`, `usage_event`, or an input item).
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more items exist beyond this page. Currently always `false`, because lists return in full. Branch on this rather than assuming a single page.
</ResponseField>

## Endpoints that return lists [#endpoints-that-return-lists]

| Endpoint                                                  | `data` element | Notes                                                                                                 |
| --------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| [`GET /v1/models`](/api-v1/models)                        | `model`        | All aliases and provider models, sorted by id.                                                        |
| [`GET /v1/responses/{id}/input_items`](/api-v1/responses) | input item     | The items that produced a response, when full-fidelity retention is enabled; otherwise an empty list. |
| [`GET /v2/usage`](/api-v2/usage)                          | `usage_event`  | Per-request usage. Filter and group with query parameters.                                            |

## Practical guidance [#practical-guidance]

Because lists return complete, you do not need a paging loop today. Read `data` directly. If you want to be forward-compatible, treat a `true` value of `has_more` as a signal to fetch the next page once a cursor parameter is introduced, and do not hardcode an assumption that `data` is the entire collection.

```python
resp = client.models.list()        # OpenAI SDK against https://api.zumik.ai/v1
for model in resp.data:
    print(model.id)
# resp.has_more is False today; check it rather than assuming.
```

The native [usage](/api-v2/usage) endpoint accepts query parameters to scope and group results, which is the right lever when a raw list would be large.