# Pagination

The public API pages in two ways: lists, which know how many items they hold,
and dataset rows, which do not.

## Lists

Every list endpoint — `/v1/projects`, `/v1/projects/{project_id}/datasets`,
`/v1/projects/{project_id}/nodes` — takes the same two parameters:

| Parameter | Default | Range | Meaning |
| --- | --- | --- | --- |
| `page` | 1 | from 1 | Page number, **1-based**. |
| `size` | 50 | 1–100 | Items per page. |

```bash
curl -H "X-Api-Key: mvk_…" \
  "https://api.muviabi.com/api/public/v1/projects?page=2&size=20"
```

and answers with the same page shape:

```json
{
  "items": [ … ],
  "total": 37,
  "page": 2,
  "size": 20,
  "pages": 2
}
```

| Field | Meaning |
| --- | --- |
| `items` | The resources on this page. |
| `total` | How many resources the whole list holds. |
| `page` | The page you asked for. |
| `size` | The page size you asked for. |
| `pages` | How many pages the list has at this `size`. |

To read a whole list, start at `page=1` and continue while `page < pages`. A
page past the last one answers an empty `items` with the real `total`. A `page`
below 1 or a `size` outside 1–100 answers `422 validation_error`, with
`details` naming the parameter.

## Dataset rows

`GET /v1/projects/{project_id}/datasets/{dataset_id}/rows` reads a saved
dataset's query, and the rows of an arbitrary query cannot be counted cheaply.
So a page of rows has no `total` and no `pages`; it says instead whether more
rows follow.

| Parameter | Range | Meaning |
| --- | --- | --- |
| `page` | from 1 | Page number, **1-based**. |
| `size` | 1–1000, default 100 | Rows per page. |

```bash
curl -H "X-Api-Key: mvk_…" \
  "https://api.muviabi.com/api/public/v1/projects/<project_id>/datasets/<dataset_id>/rows?page=1&size=500"
```

```json
{
  "columns": ["timestamp", "sensor", "value"],
  "items": [
    { "timestamp": "2026-09-26T08:00:00", "sensor": "T-101", "value": 21.4 },
    { "timestamp": "2026-09-26T08:00:00", "sensor": "T-102", "value": 19.8 }
  ],
  "page": 1,
  "size": 500,
  "has_more": true
}
```

| Field | Meaning |
| --- | --- |
| `columns` | The result's column names, in order. |
| `items` | One object per row, keyed by column name. |
| `page` | The page you asked for. |
| `size` | The page size you asked for. |
| `has_more` | `true` when at least one more row follows this page. |

To read every row, start at `page=1` and continue while `has_more` is `true`.

### Row order

Rows come in the order the dataset's query returns them. A query without an
`ORDER BY` has no guaranteed order, so the same row may appear on two pages
and another on none. If you page through a dataset, make sure its query
orders its rows — the dataset is edited in Muvia, not through the API.

Rows are read live on every request: rows added while you page can shift the
pages that follow. Process rows idempotently by a key of your own.
