CDP REST APIAPI Reference
List Profiles
List and search customer profiles, bucketed into deterministic customers and pixel-only anonymous profiles.
GET /cdp/profiles — list / search the brand's profiles, scoped to your shop.
Request
GET /cdp/profiles
Authorization: Bearer vyg_…Query parameters
| Param | Type | Default | Description |
|---|---|---|---|
bucket | customers | anonymous | customers | customers = deterministically-resolved identities (provenance server); anonymous = pixel-only profiles (provenance pixel). The two are never co-mingled. |
q | string | — | Search term. |
limit | integer | 25 | Page size, clamped to a maximum of 100. |
offset | integer | 0 | Offset; offset + limit must stay within the 10,000-row window or the request is rejected 400. |
cursor | string | — | Opaque scope-bound deep-pagination token. When present, offset is ignored. |
sort | string | itemId.keyword:asc | Sort key. The default stable sort is cursor-eligible; any other sort makes the page offset-only (no cursor minted). |
Response 200
{
"bucket": "customers",
"list": [
{
"itemId": "shopify_your-shop_1234",
"properties": {},
"provenance": "server"
}
],
"identities": {
"shopify_your-shop_1234": {}
},
"totalSize": 1,
"offset": 0,
"pageSize": 25,
"scope": "your-shop.myshopify.com",
"nextCursor": null
}| Field | Type | Description |
|---|---|---|
bucket | customers | anonymous | The bucket this response reflects. |
list | array | The page of profiles. Every profile carries a required provenance label (server | pixel | merged). |
identities | object | Identity projection keyed by each profile's itemId. |
totalSize | integer | Estimated total, capped at 10,000 (see Pagination). |
offset | integer | Offset this page started at. |
pageSize | integer | Effective page size. |
scope | string | Your brand's connected shop domain. |
nextCursor | string | null | Token for the next page, or null when enumeration is exhausted. |
Provenance
A merged master (a probabilistic collapse) can appear in the customers bucket because it
carries a deterministic shopify_* id, but it is always labelled merged — never silently
server — so you never mistake it for one confirmed human.
Example
curl -s "https://cdp.vyg.app/cdp/profiles?bucket=customers&limit=25" \
-H "Authorization: Bearer vyg_your_key_here"Errors
| Status | When |
|---|---|
400 | A deep offset past the result window, or a malformed/cross-endpoint cursor. |
401 | Missing or invalid credential. |
403 | No connected shop resolves a scope; or a cursor minted for a different brand. |
405 | Non-GET method. |
See Errors for the full envelope.