DocsGet startedPagination & filters

Pagination & filters

Cursors, list parameters and valid filter values.

Envelope#

List endpoints return:

json

{ "data": [ … ], "pagination": { "total": 1284, "next_cursor": "eyJzIjpbMTcy…" } }

Pass cursor=<next_cursor> to get the next page. next_cursor: null means you reached the end. limit is 1–50 (default 20).

bash

curl "https://provly.co/api/v1/ads?query=serum&limit=50&cursor=eyJzIjpbMTcy…" -H "Authorization: Bearer $PROVLY_API_KEY"

Lists#

Query-string lists are comma separated (countries=TR,DE) or repeated (countries=TR&countries=DE). JSON bodies (POST /ads/query) take arrays.

Valid values#

Don't guess niche slugs, Shopify app ids or email types: read them from the facets endpoint, which also returns how many records use each value.

bash

curl https://provly.co/api/v1/facets/niches -H "Authorization: Bearer $PROVLY_API_KEY"
curl "https://provly.co/api/v1/facets/shop-apps?search=klaviyo" -H "Authorization: Bearer $PROVLY_API_KEY"

Facets: niches, platforms, formats, countries, languages, shop-platforms, shop-apps, technologies, themes, email-campaign-types, email-promotion-types.

Dates and ids#

Dates are ISO 8601 in UTC.
Ids are opaque strings. Ad and advertiser ids start with their source (meta_library_…, tiktok_…); keep them as they are.