Pagination and dates

Response envelopes

Single resources use { "data": { ... } }. List responses use data and, where supported, pagination:

{
  "data": [],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false, "total": 0 }
}

total can be null when a total count is not available cheaply. Read each endpoint’s schema; visibility returns its supported report shape without cursor parameters.

Cursor pagination

For endpoints with pagination, limit is 1-200 and defaults to 50. Pass next_cursor from one response as the next request’s cursor. Keep the original filters unchanged. Stop when next_cursor is null.

Cursors are opaque. Do not decode, edit, or construct them. A malformed cursor returns invalid_cursor.

Dates

Where supported, start_date and end_date are inclusive dates in YYYY-MM-DD format, interpreted in UTC. The default window is the 30 days ending today. The maximum span is 366 days. The start cannot follow the end.

Rankings, visibility and competitors accept date ranges. Citations instead expose rolling 90-day and all-time measures. Do not assume every endpoint accepts every filter.

Metric values

Fields use snake_case. Rates are percentages on a 0-100 scale. Timestamps are ISO 8601 in UTC. A nullable value means unavailable, not zero; preserve that distinction in charts and calculations. Each endpoint lists the supported fields and their descriptions.