Pagination

The list envelope every VYG API list returns, and how to page through it with a cursor.

Every list endpoint returns the same envelope, { data, next_cursor }. You page with limit and cursor query parameters. The REST reference shows the parameters of each endpoint.

The list envelope: `{ data, next_cursor }`

{
	"data": [
		/* records */
	],
	"next_cursor": "eyJpZCI6IjhmMmIwYzFlIn0"
}

Field	Meaning
`data`	The page of records.
`next_cursor`	Opaque cursor of the next page. `null` on the last page, and always `null` on an unpaged list.

Two lists add one field beside the page: segment members add generation, and the customer field catalog (GET /v1/customers/fields) adds catalog_version. Single records and reports are not wrapped in data; they are returned as the object itself.

Query param	Description
`limit`	Page size. The default and maximum depend on the endpoint; see the table below.
`cursor`	The `next_cursor` from the previous page. Omit it for the first page.

No list takes an offset, and no list returns a total count. The lists that used to page by offset (commerce orders and subscriptions, customers at risk, conversation insights and the conversations for an insight) refuse an offset parameter with 400 bad_request.

Page sizes

Endpoints	Default	Maximum	Over the maximum
Conversations, messages, contacts	50	100	Reduced to 100
Customers: list, timeline, orders, subscriptions	50	200	`400 bad_request`
Customer search (`GET /v1/customers/search`)	25	25	`400 bad_request`
Segment members (`GET /v1/segments/{id}/members`)	100	5,000	`400 bad_request`
Segment history	100	1,000	`400 bad_request`
Segments list (`GET /v1/segments`)	200	500	`400 bad_request`
Commerce orders, subscriptions and products; customers at risk	25	100	`400 bad_request`
Conversation insights (`GET /v1/brand/insights`)	20	50	`400 bad_request`
Conversations for an insight (`GET /v1/brand/insights/{insight_id}/conversations`)	10	30	`400 bad_request`

Use the largest page the endpoint allows when you need every record; it means fewer requests.

Walk every page

Request the first page with no cursor.
While next_cursor is not null, request the next page with cursor=<next_cursor> and the same filters and limit.

# First page
curl -sS "https://api.vyg.app/v1/conversations?limit=50" \
  -H "Authorization: Bearer $VYG_API_KEY"

# Next page
curl -sS "https://api.vyg.app/v1/conversations?limit=50&cursor=eyJpZCI6IjhmMmIwYzFlIn0" \
  -H "Authorization: Bearer $VYG_API_KEY"

Treat the cursor as opaque: do not parse or build one, and do not reuse it with different filters. A cursor that the API did not issue returns 400 bad_request rather than restarting from the beginning.

MCP list tools page the same way: the tool result has data and next_cursor, and the tool takes a cursor argument.

Commerce orders, subscriptions and customers at risk

These lists stop at row 10,000. The page that reaches row 10,000 is shortened to end there and its next_cursor is null. A cursor at or past row 10,000 returns 400 bad_request. Narrow the request with the endpoint's filters (dates, status, customer) to reach older rows.

Products

GET /v1/commerce/products reads the live store catalog, and its next_cursor comes from the store. Pass it back as cursor until it is null.

Unpaged lists

Some lists return every record in one response and always set next_cursor to null: providers, event definitions, keys, event types, connected apps (GET /v1/integrations), campaigns, the customer field catalog, customer search and conversation search. They use the same { data, next_cursor } envelope, so the same client code reads them.