# Pagination

Source: https://developers.novilabs.com/platform/pagination/

> How each Novi product splits large results, page sizes, and how to pull only what changed.

## At a glance

| Product | How it pages | Page size | End of results |
| --- | --- | --- | --- |
| Novi UDM Data over HTTPS | Snowflake returns results in partitions. The first comes with the response; fetch the rest with `GET /api/v2/statements/<statementHandle>?partition=<n>` | Set by Snowflake. `resultSetMetaData.partitionInfo` lists each partition's rows and size | The last partition listed in `partitionInfo` |
| Novi Forecasts API | `limit` and an opaque `cursor`. Pass `next_cursor` back with the same filters and sort | `GET /plans`: 1 to 100, default 20. `GET /plans/{id}/curves`: 1 to 200 wells, default 100 | `next_cursor` is `null` |
| Novi EVA REST API | No paging. Send wells in batches | `POST /v1/data`: up to 50,000 wells. `POST /v1/production`: up to 1,000 wells | One call. On `POST /v1/data`, wells come back in request order |
| Novi EVA MCP server | `fetch_data` returns `next_cursor`. Send every original input again with `cursor` set | `fetch_data`: default 100 rows, up to 500. `search_columns`: default 20, up to 50. `get_map_legend`: up to 200 | No `next_cursor` |
| Novi M&A Intelligence MCP server | `limit` and `offset` on `ma_search_deals` and `ma_table_deals` | Up to 100 rows | Not published yet |

## Novi UDM Data (v4)

In SQL you choose the rows: filter, aggregate and name only the columns you need. Over HTTPS, read the partitions as the table above shows. Snowflake documents them at docs.snowflake.com/en/developer-guide/sql-api/handling-responses.

For a full copy, use [bulk files](https://developers.novilabs.com/data/delivery/#bulk-files) instead of paging through queries.

## Novi Forecasts API

- On `GET /plans`, plans created or deleted between pages are neither skipped nor repeated.
- Curve pages carry an `ETag`. Send it back as `If-None-Match`: a Not Modified answer means nothing moved.

Details: [Jobs, waiting and retries](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/).

## Novi EVA MCP server

- A cursor works only with the inputs it came from, for 10 minutes. Otherwise you get `INVALID_CURSOR`: start again without one.
- Pages are not a snapshot. Data can change between pages.

## Pull only what changed

| Product | How |
| --- | --- |
| Novi UDM Data (v4) | Bulk diff zips: apply each diff in `RUN_ID` order. `DOWNLOADS_DIFF` keeps the last 7 runs. In SQL, 22 of the 29 base views carry `UPDATED_AT` |
| Novi Forecasts API | `GET /plans` with `kept=true`, `status=done` and `updated_from`. See [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/) |
| Novi EVA API | Not published yet |

Forecasts lists never report removals: run a full list now and then to catch them. Novi UDM Data diff zips do carry deletes.
