Trendtrack
ReferenceAPI

Brandtrackers

Returns the workspace-scoped active brandtrackers attached to the authenticated public API workspace. The public identifier is brandtracker.id; V2 brandtracker ids from before the V3 cutover are also accepted.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

page?integer
limit?integer
hasNewAdsSince?string

ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.

name?string

Case-insensitive contains match against brandtracker name.

sortBy?string

Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.

folderIds?array<>

Folder ids. Repeated query params and comma-separated values are both accepted.

folderNames?array<string>

Folder name search terms. Matches are case-insensitive contains checks. Repeated query params and comma-separated values are both accepted.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",      "name": "Example Brand",      "facebookPageId": "61554990830184",      "workspaceLinkId": 99,      "targetType": "shop",      "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",      "domain": "examplebrand.com",      "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",      "status": {        "isLoaded": true,        "lastCrawledAt": "2026-04-20T10:00:00.000Z"      },      "workspaceAddedAt": "2026-04-15T09:00:00.000Z",      "folder": {        "id": 42,        "name": "Competitors"      },      "advertising": {        "activeAds": 18,        "newAdsLastDay": 3,        "newAdsLast7Days": 11,        "newAdsLast30Days": 34      },      "websites": [        {          "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",          "domain": "examplebrand.com",          "siteName": "Example Brand",          "trafficNumber": 145230,          "trafficChange": 12.4,          "monthlyTraffic": {            "2026-01": 102343,            "2026-02": 114230          },          "socialNetworks": {            "facebook": "https://facebook.com/examplebrand",            "instagram": "https://instagram.com/examplebrand",            "youtube": "https://youtube.com/@examplebrand"          }        }      ],      "totalTraffic": 145230    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 128,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Creates or reactivates a workspace brandtracker by exactly one target identifier: facebookPageId, websiteId, shopId (alias of websiteId), or domain. Domains are normalized and must resolve to exactly one known website. State-changing create/reactivate requests consume one brandtracker create/delete quota unit and one active brandtracker slot; already-active no-ops return 200 and cost 0 units.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

facebookPageId?string

Meta/Facebook page identifier to track. Exactly one of facebookPageId, websiteId, shopId, or domain is required.

websiteId?string

Website/shop identifier to track as a shop-level brandtracker. Exactly one target identifier is accepted.

shopId?string

Alias of websiteId for shop-oriented clients. Exactly one target identifier is accepted.

domain?string

Shop domain to resolve to exactly one known website and track as a shop-level brandtracker. Protocols, paths, and a leading www. are normalized away.

folderId?|

Workspace brandtracker folder id. Null or omitted attaches the brandtracker at root.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/brandtrackers" \  -H "Content-Type: application/json" \  -d '{}'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",    "name": "Example Brand",    "facebookPageId": "61554990830184",    "workspaceLinkId": 99,    "targetType": "shop",    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",    "domain": "examplebrand.com",    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",    "status": {      "isLoaded": true,      "lastCrawledAt": "2026-04-20T10:00:00.000Z"    },    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",    "folder": {      "id": 42,      "name": "Competitors"    },    "advertising": {      "activeAds": 18,      "newAdsLastDay": 3,      "newAdsLast7Days": 11,      "newAdsLast30Days": 34    },    "websites": [      {        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",        "domain": "examplebrand.com",        "siteName": "Example Brand",        "trafficNumber": 145230,        "trafficChange": 12.4,        "monthlyTraffic": {          "2026-01": 102343,          "2026-02": 114230        },        "socialNetworks": {          "facebook": "https://facebook.com/examplebrand",          "instagram": "https://instagram.com/examplebrand",          "youtube": "https://youtube.com/@examplebrand"        }      }    ],    "totalTraffic": 145230  },  "created": true}
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",    "name": "Example Brand",    "facebookPageId": "61554990830184",    "workspaceLinkId": 99,    "targetType": "shop",    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",    "domain": "examplebrand.com",    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",    "status": {      "isLoaded": true,      "lastCrawledAt": "2026-04-20T10:00:00.000Z"    },    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",    "folder": {      "id": 42,      "name": "Competitors"    },    "advertising": {      "activeAds": 18,      "newAdsLastDay": 3,      "newAdsLast7Days": 11,      "newAdsLast30Days": 34    },    "websites": [      {        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",        "domain": "examplebrand.com",        "siteName": "Example Brand",        "trafficNumber": 145230,        "trafficChange": 12.4,        "monthlyTraffic": {          "2026-01": 102343,          "2026-02": 114230        },        "socialNetworks": {          "facebook": "https://facebook.com/examplebrand",          "instagram": "https://instagram.com/examplebrand",          "youtube": "https://youtube.com/@examplebrand"        }      }    ],    "totalTraffic": 145230  },  "created": true}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "quota_exhausted",    "message": "string",    "requestId": "string",    "details": {      "feature": "brandtracker_v3",      "limit": 10,      "used": 10,      "reservedByCooldown": 2,      "nextSlotAvailableAt": "2026-09-26T09:30:00.000Z",      "currentUsage": 10,      "maxLimit": 10    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the active workspace brandtracker folders so clients can resolve folder ids for brandtracker filters. Equivalent folder listing is also available at GET /v1/workspace/folders.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/folders"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": 12,      "name": "Competitors",      "rank": 1,      "brandtrackerCount": 8    }  ]}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Creates a workspace brandtracker folder and assigns the next rank atomically. Folder mutations are workspace-scoped, metered, and audited.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Workspace-scoped folder name. Rank is assigned atomically as the next workspace rank.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/brandtrackers/folders" \  -H "Content-Type: application/json" \  -d '{    "name": "Competitors"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": 12,    "name": "Competitors",    "rank": 1,    "brandtrackerCount": 8  }}
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": 12,    "name": "Competitors",    "rank": 1,    "brandtrackerCount": 8  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Renames a workspace brandtracker folder. The folder id must belong to the authenticated workspace; cross-workspace ids are returned as not found before any state change.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

New workspace-scoped folder name.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/brandtrackers/folders/1" \  -H "Content-Type: application/json" \  -d '{    "name": "Priority Competitors"  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": 12,    "name": "Competitors",    "rank": 1,    "brandtrackerCount": 8  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Deletes a workspace folder. move-to-default moves active brandtrackers to root; delete-brandtrackers deactivates affected workspace links. confirm must be true. The delete-brandtrackers action consumes one persistent brandtracker create/delete quota operation for the whole folder and decrements active brandtracker usage by the affected active-link count; no partial mutation is committed when quota is exhausted.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

action*string

move-to-default keeps affected trackers active and clears their folder. delete-brandtrackers deactivates affected active workspace links, consumes one persistent create/delete quota unit for the whole folder delete, and decrements active brandtracker usage by affectedCount.

confirm*boolean

Must be true for destructive folder delete requests.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/brandtrackers/folders/1" \  -H "Content-Type: application/json" \  -d '{    "action": "move-to-default",    "confirm": true  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "deleted": true,    "action": "move-to-default",    "affectedCount": 12  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Moves active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. The destination folder id must belong to the authenticated workspace; null moves links to root. Move operations are metered and audited but do not consume persistent create/delete quota or change active brandtracker usage.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brandtrackerIds?array<string>

Public brandtracker ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required.

workspaceLinkIds?array<number>

Workspace link ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required.

folderId*|

Destination workspace folder id, or null to move to root.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/brandtrackers/workspace-links" \  -H "Content-Type: application/json" \  -d '{    "folderId": 42  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "requestedCount": 3,    "affectedCount": 2,    "notFoundBrandtrackerIds": [      "string"    ],    "notFoundWorkspaceLinkIds": [      0    ],    "cooldownUntil": "2026-09-26T09:30:00.000Z"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Deactivates active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. confirm must be true. Bulk delete consumes one persistent brandtracker create/delete quota operation for the request, reports requested/affected/not-found ids, and decrements active brandtracker usage by the affected active-link count.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brandtrackerIds?array<string>

Public brandtracker ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required.

workspaceLinkIds?array<number>

Workspace link ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required.

confirm*boolean

Must be true for destructive bulk delete requests.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/brandtrackers/workspace-links" \  -H "Content-Type: application/json" \  -d '{    "confirm": true  }'
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "requestedCount": 3,    "affectedCount": 2,    "notFoundBrandtrackerIds": [      "string"    ],    "notFoundWorkspaceLinkIds": [      0    ],    "cooldownUntil": "2026-09-26T09:30:00.000Z"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the detail payload for one active workspace brandtracker resolved from brandtracker.id.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",    "name": "Example Brand",    "facebookPageId": "61554990830184",    "workspaceLinkId": 99,    "targetType": "shop",    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",    "domain": "examplebrand.com",    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",    "status": {      "isLoaded": true,      "lastCrawledAt": "2026-04-20T10:00:00.000Z"    },    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",    "folder": {      "id": 42,      "name": "Competitors"    },    "advertising": {      "activeAds": 18,      "newAdsLastDay": 3,      "newAdsLast7Days": 11,      "newAdsLast30Days": 34    },    "websites": [      {        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",        "domain": "examplebrand.com",        "siteName": "Example Brand",        "trafficNumber": 145230,        "trafficChange": 12.4,        "monthlyTraffic": {          "2026-01": 102343,          "2026-02": 114230        },        "socialNetworks": {          "facebook": "https://facebook.com/examplebrand",          "instagram": "https://instagram.com/examplebrand",          "youtube": "https://youtube.com/@examplebrand"        }      }    ],    "totalTraffic": 145230,    "createdAt": "2026-04-01T12:00:00.000Z",    "updatedAt": "2026-04-21T09:30:00.000Z",    "pageProfile": {      "about": "Global fashion brand",      "category": "Clothing (Brand)",      "facebookLikes": 523400,      "instagramFollowers": 841200,      "instagramUsername": "examplebrand",      "profileUri": "https://www.facebook.com/examplebrand",      "runningAds": 18    },    "statistics": {      "urlCount": {        "https://examplebrand.com/products/hero": 14      },      "ctaCount": {        "SHOP_NOW": 10,        "LEARN_MORE": 4      },      "liveAdCount": {        "activeCount": 18,        "inactiveCount": 4      },      "formatCount": {        "IMAGE": 8,        "VIDEO": 10      },      "euData": null    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Marks the workspace brandtracker inactive while preserving the workspace link and workspace-scoped metadata for reconstructability/reactivation. The shared global brandtracker row is preserved.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",    "deleted": true,    "cooldownUntil": "2026-09-26T09:30:00.000Z"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the workspace-scoped active brandtrackers assigned to the requested folder. This is equivalent to /v1/brandtrackers?folderIds=:folderId.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Workspace brandtracker folder id.

Query Parameters

page?integer
limit?integer
hasNewAdsSince?string

ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.

name?string

Case-insensitive contains match against brandtracker name.

sortBy?string

Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/folders/1/brandtrackers"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",      "name": "Example Brand",      "facebookPageId": "61554990830184",      "workspaceLinkId": 99,      "targetType": "shop",      "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",      "domain": "examplebrand.com",      "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",      "status": {        "isLoaded": true,        "lastCrawledAt": "2026-04-20T10:00:00.000Z"      },      "workspaceAddedAt": "2026-04-15T09:00:00.000Z",      "folder": {        "id": 42,        "name": "Competitors"      },      "advertising": {        "activeAds": 18,        "newAdsLastDay": 3,        "newAdsLast7Days": 11,        "newAdsLast30Days": 34      },      "websites": [        {          "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",          "domain": "examplebrand.com",          "siteName": "Example Brand",          "trafficNumber": 145230,          "trafficChange": 12.4,          "monthlyTraffic": {            "2026-01": 102343,            "2026-02": 114230          },          "socialNetworks": {            "facebook": "https://facebook.com/examplebrand",            "instagram": "https://instagram.com/examplebrand",            "youtube": "https://youtube.com/@examplebrand"          }        }      ],      "totalTraffic": 145230    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 128,    "totalPages": 6  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns available ad reach snapshot dates and readiness status for one active workspace brandtracker. latestDate is preserved as a compatibility alias of latestReadyDate; snapshotDate=latest resolves to the latest ready date.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of snapshot dates to return. Defaults to 100.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/snapshots"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "latestDate": "2026-04-20",    "latestReadyDate": "2026-04-20",    "latestScheduledDate": "2026-04-21",    "dates": [      "2026-04-20",      "2026-04-19"    ],    "snapshots": [      {        "date": "2026-04-23",        "status": "ready",        "usableRows": 1240,        "indexedRows": 1300      }    ]  },  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the Meta ads for one active workspace brandtracker resolved from brandtracker.id to fb_page_id. The response reuses the public ad summary shape.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer
limit?integer
sortBy?string

Sort key. The adOrder value also accepts ad_order and ad-order aliases.

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?string
createdBefore?string
minDaysRunning?integer
maxDaysRunning?integer
minDuplicates?integer
maxDuplicates?integer
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?number
maxSpend?number
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?number
maxSpendPerPage?number
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer
maxAge?integer
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?integer
maxFacebookLikes?integer
minInstagramFollowers?integer
maxInstagramFollowers?integer
minVideoDuration?number
maxVideoDuration?number
minDescriptionLength?integer
maxDescriptionLength?integer
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/ads"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "facebook_123456789",      "collationId": "3810635369204881",      "platform": "facebook",      "status": "active",      "createdAt": "2026-04-18T12:30:00.000Z",      "firstSeenAt": "2026-04-10T00:00:00.000Z",      "lastSeenAt": "2026-04-19T00:00:00.000Z",      "daysRunning": 9,      "media": {        "type": "video",        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"      },      "advertiser": {        "id": "1234567890",        "name": "Example Brand",        "logoUrl": "https://cdn.example.com/pages/example-brand.png",        "facebookPageId": "1234567890",        "liveAdsCount": 42,        "reach30d": 152340,        "totalReach": 842100,        "countriesCount": 8,        "facebookLikes": 125000,        "instagramFollowers": 89000      },      "content": {        "title": "Summer Sale",        "body": "Up to 30% off selected products.",        "transcript": "Save 30% on every order.",        "callToAction": "Shop now",        "landingPageUrl": "https://example.com/products/summer-sale",        "landingPageDomain": "example.com",        "ctaDescription": "Free shipping on orders over $50.",        "ctaLinkDescription": "Shop the full collection"      },      "metrics": {        "reach": 152340,        "aggregatedReach": 284100,        "estimatedSpend": 4262,        "duplicates": 4,        "reachDelta1d": 1200,        "reachDelta7d": 8200,        "reachDelta30d": 38400      },      "audience": {        "targetedCountries": [          "US",          "FR"        ],        "mainCountry": "FR",        "gender": "all",        "ageMin": 18,        "ageMax": 65      },      "rank": {        "positionInPage": 3,        "currentRank": 12,        "rankDelta": -4,        "improvementPct": 0.25      },      "flags": {        "isEuAd": true,        "isLowReach": false,        "isMediaChanged": false,        "hasPartnerBadge": true      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 235,    "totalPages": 10  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns deduped Meta partnership ad groups for one active workspace brandtracker. This endpoint always filters to ads with a partner badge and reuses the public ad summary shape.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer
limit?integer
sortBy?string

Sort key. The adOrder value also accepts ad_order and ad-order aliases.

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?string
createdBefore?string
minDaysRunning?integer
maxDaysRunning?integer
minDuplicates?integer
maxDuplicates?integer
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?number
maxSpend?number
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?number
maxSpendPerPage?number
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer
maxAge?integer
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?integer
maxFacebookLikes?integer
minInstagramFollowers?integer
maxInstagramFollowers?integer
minVideoDuration?number
maxVideoDuration?number
minDescriptionLength?integer
maxDescriptionLength?integer
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

partnerId?string

Single partner identifier alias. It is merged with partnerIds when both are provided.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/partnership-ads"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "facebook_123456789",      "collationId": "3810635369204881",      "platform": "facebook",      "status": "active",      "createdAt": "2026-04-18T12:30:00.000Z",      "firstSeenAt": "2026-04-10T00:00:00.000Z",      "lastSeenAt": "2026-04-19T00:00:00.000Z",      "daysRunning": 9,      "media": {        "type": "video",        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"      },      "advertiser": {        "id": "1234567890",        "name": "Example Brand",        "logoUrl": "https://cdn.example.com/pages/example-brand.png",        "facebookPageId": "1234567890",        "liveAdsCount": 42,        "reach30d": 152340,        "totalReach": 842100,        "countriesCount": 8,        "facebookLikes": 125000,        "instagramFollowers": 89000      },      "content": {        "title": "Summer Sale",        "body": "Up to 30% off selected products.",        "transcript": "Save 30% on every order.",        "callToAction": "Shop now",        "landingPageUrl": "https://example.com/products/summer-sale",        "landingPageDomain": "example.com",        "ctaDescription": "Free shipping on orders over $50.",        "ctaLinkDescription": "Shop the full collection"      },      "metrics": {        "reach": 152340,        "aggregatedReach": 284100,        "estimatedSpend": 4262,        "duplicates": 4,        "reachDelta1d": 1200,        "reachDelta7d": 8200,        "reachDelta30d": 38400      },      "audience": {        "targetedCountries": [          "US",          "FR"        ],        "mainCountry": "FR",        "gender": "all",        "ageMin": 18,        "ageMax": 65      },      "rank": {        "positionInPage": 3,        "currentRank": 12,        "rankDelta": -4,        "improvementPct": 0.25      },      "flags": {        "isEuAd": true,        "isLowReach": false,        "isMediaChanged": false,        "hasPartnerBadge": true      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 235,    "totalPages": 10  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the deduped public ad group count matching the partnership ads list filters. This intentionally matches public list pagination semantics rather than the webapp raw active badge count.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?string
createdBefore?string
minDaysRunning?integer
maxDaysRunning?integer
minDuplicates?integer
maxDuplicates?integer
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?number
maxSpend?number
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?number
maxSpendPerPage?number
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer
maxAge?integer
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?integer
maxFacebookLikes?integer
minInstagramFollowers?integer
maxInstagramFollowers?integer
minVideoDuration?number
maxVideoDuration?number
minDescriptionLength?integer
maxDescriptionLength?integer
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

partnerId?string

Single partner identifier alias. It is merged with partnerIds when both are provided.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/partnership-ads/count"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "count": 0  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns grouped hook analytics for the requested brandtracker using the authenticated workspace as the only access scope.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional hook sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/hooks"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "hook": "Stop scrolling.",      "usageCount": 12,      "longestRunning": 47,      "totalImpressions": 152340,      "firstUsedAt": "2026-02-01T09:12:00.000Z",      "lastUsedAt": "2026-04-19T12:30:00.000Z",      "sampleAd": {        "adId": "facebook_123456789",        "mediaUrl": "https://cdn.example.com/ads/creative.mp4",        "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg",        "fullText": "This is the full transcript text for the sampled ad."      }    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns grouped transcript/script analytics for the requested brandtracker using the authenticated workspace as the only access scope.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional transcript sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/transcripts"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "fullText": "This is the full transcript text used by multiple ads in this brandtracker.",      "usageCount": 12,      "longestRunning": 47,      "totalImpressions": 152340,      "firstUsedAt": "2026-02-01T09:12:00.000Z",      "lastUsedAt": "2026-04-19T12:30:00.000Z",      "sampleAd": {        "adId": "facebook_123456789",        "mediaUrl": "https://cdn.example.com/ads/creative.mp4",        "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg"      }    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns grouped headline analytics for the requested brandtracker.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional headline sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/headlines"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "headline": "Summer sale is live",      "usageCount": 18,      "longestRunning": 52    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns grouped ad copy analytics for the requested brandtracker.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional ad copy sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/ad-copies"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "adCopy": "Get 30% off selected products this week only.",      "usageCount": 21,      "longestRunning": 43    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns grouped landing page analytics for the requested brandtracker, including detected technologies when available.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional landing page sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/landing-pages"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "landingPage": "https://example.com/products/summer-sale",      "usageCount": 16,      "longestRunning": 41,      "totalImpressions": 305400,      "technologies": [        {          "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",          "name": "Shopify",          "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"        }      ],      "screenshots": {        "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",        "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",        "head": "https://cdn.example.com/screenshots/landing-page-head.png"      }    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns normalized/grouped landing page analytics for the requested brandtracker. Query strings, fragments, trailing slashes, and leading www. hostnames are ignored for grouping.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional normalized landing page sorting. Defaults to usageCount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/landing-pages/simple"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "landingPage": "https://example.com/products/summer-sale",      "normalizedLandingPage": "example.com/products/summer-sale",      "usageCount": 16,      "activeAdsCount": 5,      "technologies": [        {          "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",          "name": "Shopify",          "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"        }      ],      "screenshots": {        "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",        "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",        "head": "https://cdn.example.com/screenshots/landing-page-head.png"      }    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns paginated creative analytics for the requested brandtracker.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional creatives sorting. Defaults to firstSeenAt.

mediaType?string

Optional media type filter. Defaults to all.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/creatives"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "adId": "facebook_123456789",      "mediaType": "video",      "mediaUrl": "https://cdn.example.com/ads/creative.mp4",      "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg",      "firstSeenAt": "2026-03-01T08:00:00.000Z",      "daysRunning": 27,      "duplicates": 4    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns paginated partnership analytics for the requested brandtracker.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

order?string

Optional sort order. Defaults to desc.

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

sortBy?string

Optional partners sorting. Defaults to activeAds.

cpm?number

Optional CPM used to estimate spend from reach. Defaults to 9.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/partners"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "facebookPageId": "61554990830184",      "name": "Example Partner",      "activeAds": 8,      "launchDate": "2026-02-18T13:40:00.000Z",      "reach": 245000,      "estimatedSpend": 2205    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the media-format breakdown (image, video, dco, other) for the brandtracker's deduped currently active ads, or a deduped snapshot reconstruction when a snapshotDate is provided. activeAds equals the sum of the media buckets.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

snapshotDate?string

Optional snapshot date (YYYY-MM-DD or latest). When provided, the mix is reconstructed for that date; otherwise it uses live active ads. Counts are deduped by ad before media buckets are calculated.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/media-mix"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "activeAds": 23,    "formatCount": {      "image": 12,      "video": 8,      "dco": 2,      "other": 1    }  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns the EU country / age / gender reach distributions precomputed for the brandtracker. The underlying dataset is page-level and EU-only, so this endpoint is fundamentally EU-scoped.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

euOnly?boolean

EU-only filter. This endpoint is fundamentally EU-scoped (the source data is the EU-only fb_page_reach_by_country table), so this defaults to true and is retained for forward compatibility.

snapshotDate?string

Optional snapshot date (YYYY-MM-DD or latest). The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.

timePeriod?string

Optional time window. The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/demography"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "hasData": true,    "countryDistribution": [      {        "countryCode": "US",        "reach": 125000      }    ],    "ageDistribution": [      {        "ageRange": "25-34",        "reach": 82000      }    ],    "genderDistribution": [      {        "gender": "female",        "reach": 91000      }    ]  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Canonical current-ranking endpoint for a brandtracker. Use sortBy=currentRank for the current Facebook page rank, sortBy=reach/reachDelta1d/reachDelta7d/reachDelta30d for reach rankings, and sortBy=rankDelta7d/rankDelta14d/rankDelta30d for rank movers. period and snapshotDate are deprecated compatibility parameters and are ignored on this current-ranking path.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

facebookPageId?string

Optional Facebook page id belonging to this brandtracker. When omitted, the primary Facebook page is used.

allFacebookPages?boolean

When true, aggregate all selected Facebook pages. Current ranks are page-local, so ties across pages are expected. Cannot be combined with facebookPageId.

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

sortBy?string

Sort key for canonical current rankings. Use currentRank for the selected Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings.

status?string

Preferred activity filter. active returns active ads, inactive returns inactive ads, all returns both. When supplied, it takes precedence over includeInactive.

includeInactive?boolean
Deprecated

Deprecated. When status is omitted, includeInactive=true maps to status=all; ignored when status is supplied.

period?string

Optional rolling top-ads period. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.

snapshotDate?|
Deprecated

Deprecated compatibility parameter accepted but ignored by canonical top-ads current ranking. Use freshness/system endpoints for snapshot availability checks.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/top-ads"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "ad": {        "id": "facebook_123456789",        "collationId": "3810635369204881",        "platform": "facebook",        "status": "active",        "createdAt": "2026-04-18T12:30:00.000Z",        "firstSeenAt": "2026-04-10T00:00:00.000Z",        "lastSeenAt": "2026-04-19T00:00:00.000Z",        "daysRunning": 9,        "media": {          "type": "video",          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"        },        "advertiser": {          "id": "1234567890",          "name": "Example Brand",          "logoUrl": "https://cdn.example.com/pages/example-brand.png",          "facebookPageId": "1234567890",          "liveAdsCount": 42,          "reach30d": 152340,          "totalReach": 842100,          "countriesCount": 8,          "facebookLikes": 125000,          "instagramFollowers": 89000        },        "content": {          "title": "Summer Sale",          "body": "Up to 30% off selected products.",          "transcript": "Save 30% on every order.",          "callToAction": "Shop now",          "landingPageUrl": "https://example.com/products/summer-sale",          "landingPageDomain": "example.com",          "ctaDescription": "Free shipping on orders over $50.",          "ctaLinkDescription": "Shop the full collection"        },        "metrics": {          "reach": 152340,          "aggregatedReach": 284100,          "estimatedSpend": 4262,          "duplicates": 4,          "reachDelta1d": 1200,          "reachDelta7d": 8200,          "reachDelta30d": 38400        },        "audience": {          "targetedCountries": [            "US",            "FR"          ],          "mainCountry": "FR",          "gender": "all",          "ageMin": 18,          "ageMax": 65        },        "rank": {          "positionInPage": 3,          "currentRank": 12,          "rankDelta": -4,          "improvementPct": 0.25        },        "flags": {          "isEuAd": true,          "isLowReach": false,          "isMediaChanged": false,          "hasPartnerBadge": true        }      },      "metrics": {        "totalReach": 152340,        "duplicateCount": 4,        "daysRunning": 27,        "currentRank": 3      }    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "reason": "no_snapshot_for_period"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Compatibility endpoint for clients that still call /ad-rank. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

timeWindow?string

Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.

sortBy?string

Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.

snapshotDate?string
Deprecated

Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.

maxCurrentRank?integer

Optional maximum current rank filter. Only ads at or above this current rank are returned.

minRankDelta?integer

Minimum positive rank improvement required for an ad to be returned. Defaults to 1.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/ad-rank"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "ad": {        "id": "facebook_123456789",        "collationId": "3810635369204881",        "platform": "facebook",        "status": "active",        "createdAt": "2026-04-18T12:30:00.000Z",        "firstSeenAt": "2026-04-10T00:00:00.000Z",        "lastSeenAt": "2026-04-19T00:00:00.000Z",        "daysRunning": 9,        "media": {          "type": "video",          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"        },        "advertiser": {          "id": "1234567890",          "name": "Example Brand",          "logoUrl": "https://cdn.example.com/pages/example-brand.png",          "facebookPageId": "1234567890",          "liveAdsCount": 42,          "reach30d": 152340,          "totalReach": 842100,          "countriesCount": 8,          "facebookLikes": 125000,          "instagramFollowers": 89000        },        "content": {          "title": "Summer Sale",          "body": "Up to 30% off selected products.",          "transcript": "Save 30% on every order.",          "callToAction": "Shop now",          "landingPageUrl": "https://example.com/products/summer-sale",          "landingPageDomain": "example.com",          "ctaDescription": "Free shipping on orders over $50.",          "ctaLinkDescription": "Shop the full collection"        },        "metrics": {          "reach": 152340,          "aggregatedReach": 284100,          "estimatedSpend": 4262,          "duplicates": 4,          "reachDelta1d": 1200,          "reachDelta7d": 8200,          "reachDelta30d": 38400        },        "audience": {          "targetedCountries": [            "US",            "FR"          ],          "mainCountry": "FR",          "gender": "all",          "ageMin": 18,          "ageMax": 65        },        "rank": {          "positionInPage": 3,          "currentRank": 12,          "rankDelta": -4,          "improvementPct": 0.25        },        "flags": {          "isEuAd": true,          "isLowReach": false,          "isMediaChanged": false,          "hasPartnerBadge": true        }      },      "metrics": {        "currentRank": 4,        "previousRank": 17,        "rankDelta": 13,        "improvementPct": 76.5      },      "trajectory": [        {          "date": "2026-04-20",          "rank": 4,          "totalAds": 250        }      ]    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Legacy compatibility endpoint for clients that still call /scaling-ads. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

limit?integer

Maximum number of items to return. Defaults to 20.

timeWindow?string

Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.

sortBy?string

Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.

snapshotDate?string
Deprecated

Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.

maxCurrentRank?integer

Optional maximum current rank filter. Only ads at or above this current rank are returned.

minRankDelta?integer

Minimum positive rank improvement required for an ad to be returned. Defaults to 1.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/scaling-ads"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "ad": {        "id": "facebook_123456789",        "collationId": "3810635369204881",        "platform": "facebook",        "status": "active",        "createdAt": "2026-04-18T12:30:00.000Z",        "firstSeenAt": "2026-04-10T00:00:00.000Z",        "lastSeenAt": "2026-04-19T00:00:00.000Z",        "daysRunning": 9,        "media": {          "type": "video",          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"        },        "advertiser": {          "id": "1234567890",          "name": "Example Brand",          "logoUrl": "https://cdn.example.com/pages/example-brand.png",          "facebookPageId": "1234567890",          "liveAdsCount": 42,          "reach30d": 152340,          "totalReach": 842100,          "countriesCount": 8,          "facebookLikes": 125000,          "instagramFollowers": 89000        },        "content": {          "title": "Summer Sale",          "body": "Up to 30% off selected products.",          "transcript": "Save 30% on every order.",          "callToAction": "Shop now",          "landingPageUrl": "https://example.com/products/summer-sale",          "landingPageDomain": "example.com",          "ctaDescription": "Free shipping on orders over $50.",          "ctaLinkDescription": "Shop the full collection"        },        "metrics": {          "reach": 152340,          "aggregatedReach": 284100,          "estimatedSpend": 4262,          "duplicates": 4,          "reachDelta1d": 1200,          "reachDelta7d": 8200,          "reachDelta30d": 38400        },        "audience": {          "targetedCountries": [            "US",            "FR"          ],          "mainCountry": "FR",          "gender": "all",          "ageMin": 18,          "ageMax": 65        },        "rank": {          "positionInPage": 3,          "currentRank": 12,          "rankDelta": -4,          "improvementPct": 0.25        },        "flags": {          "isEuAd": true,          "isLowReach": false,          "isMediaChanged": false,          "hasPartnerBadge": true        }      },      "metrics": {        "currentRank": 4,        "previousRank": 17,        "rankDelta": 13,        "improvementPct": 76.5      },      "trajectory": [        {          "date": "2026-04-20",          "rank": 4,          "totalAds": 250        }      ]    }  ],  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns a dashboard-style Brandtracker overview combining graph, media mix, top landing pages, top ads, and ads preview sections. The graph accepts timeSeriesPeriod for rolling windows or timeSeriesStartDate/timeSeriesEndDate for explicit ranges; do not combine them.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

euOnly?boolean

Optional EU-only filter forwarded to graph, media mix, landing pages, and top ads sections where supported.

snapshotDate?|

Snapshot date for dashboard time travel. Use YYYY-MM-DD or latest.

cpm?number

CPM used to estimate spend in the graph section.

timeSeriesGranularity?string

Bucket size for the graph section. Defaults to daily.

timeSeriesStartDate?string

Inclusive graph start date. Cannot be combined with timeSeriesPeriod.

timeSeriesEndDate?string

Inclusive graph end date. Cannot be combined with timeSeriesPeriod.

timeSeriesPeriod?string

Optional rolling window for the graph section. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with timeSeriesStartDate or timeSeriesEndDate; snapshotDate may anchor the window.

landingPagesTimePeriod?string

Time window for top landing pages. Defaults to live for dashboard-style current overview.

landingPagesLimit?integer

Maximum number of top landing pages to return. Defaults to 5.

topAdsLimit?integer

Maximum number of top ads to return. Defaults to 5.

adsPreviewLimit?integer

Maximum number of ads preview items to return. Defaults to 10.

topAdsSortBy?string

Optional top ads sorting. Defaults to reach when euOnly=true, otherwise daysRunning.

topAdsPeriod?string

Optional top ads period. Supports today, yesterday, last1d, last7d, last14d, last30d, and total. Defaults to total.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/overview"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "graph": {      "granularity": "daily",      "dateRange": {        "startDate": "2026-01-01",        "endDate": "2026-04-20"      },      "adsLaunched": [        {          "date": "2026-04-20",          "count": 12        }      ],      "liveAds": [        {          "date": "2026-04-20",          "count": 12        }      ],      "euImpressionsSpend": [        {          "date": "2026-04-20",          "impressions": 12450,          "cumulativeImpressions": 431200,          "estimatedSpend": 112.05        }      ],      "cpm": 9    },    "mediaMix": {      "activeAds": 23,      "formatCount": {        "image": 12,        "video": 8,        "dco": 2,        "other": 1      }    },    "topLandingPages": {      "data": [        {          "landingPage": "https://example.com/products/summer-sale",          "usageCount": 16,          "longestRunning": 41,          "totalImpressions": 305400,          "technologies": [            {              "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",              "name": "Shopify",              "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"            }          ],          "screenshots": {            "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",            "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",            "head": "https://cdn.example.com/screenshots/landing-page-head.png"          }        }      ],      "pagination": {        "page": 1,        "limit": 20,        "total": 128,        "totalPages": 7      }    },    "topAds": {      "data": [        {          "ad": {            "id": "facebook_123456789",            "collationId": "3810635369204881",            "platform": "facebook",            "status": "active",            "createdAt": "2026-04-18T12:30:00.000Z",            "firstSeenAt": "2026-04-10T00:00:00.000Z",            "lastSeenAt": "2026-04-19T00:00:00.000Z",            "daysRunning": 9,            "media": {              "type": "video",              "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",              "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"            },            "advertiser": {              "id": "1234567890",              "name": "Example Brand",              "logoUrl": "https://cdn.example.com/pages/example-brand.png",              "facebookPageId": "1234567890",              "liveAdsCount": 42,              "reach30d": 152340,              "totalReach": 842100,              "countriesCount": 8,              "facebookLikes": 125000,              "instagramFollowers": 89000            },            "content": {              "title": "Summer Sale",              "body": "Up to 30% off selected products.",              "transcript": "Save 30% on every order.",              "callToAction": "Shop now",              "landingPageUrl": "https://example.com/products/summer-sale",              "landingPageDomain": "example.com",              "ctaDescription": "Free shipping on orders over $50.",              "ctaLinkDescription": "Shop the full collection"            },            "metrics": {              "reach": 152340,              "aggregatedReach": 284100,              "estimatedSpend": 4262,              "duplicates": 4,              "reachDelta1d": 1200,              "reachDelta7d": 8200,              "reachDelta30d": 38400            },            "audience": {              "targetedCountries": [                "US",                "FR"              ],              "mainCountry": "FR",              "gender": "all",              "ageMin": 18,              "ageMax": 65            },            "rank": {              "positionInPage": 3,              "currentRank": 12,              "rankDelta": -4,              "improvementPct": 0.25            },            "flags": {              "isEuAd": true,              "isLowReach": false,              "isMediaChanged": false,              "hasPartnerBadge": true            }          },          "metrics": {            "totalReach": 152340,            "duplicateCount": 4,            "daysRunning": 27,            "currentRank": 3          }        }      ],      "pagination": {        "page": 1,        "limit": 20,        "total": 128,        "totalPages": 7      }    },    "adsPreview": {      "data": [        {          "id": "facebook_123456789",          "collationId": "3810635369204881",          "platform": "facebook",          "status": "active",          "createdAt": "2026-04-18T12:30:00.000Z",          "firstSeenAt": "2026-04-10T00:00:00.000Z",          "lastSeenAt": "2026-04-19T00:00:00.000Z",          "daysRunning": 9,          "media": {            "type": "video",            "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",            "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"          },          "advertiser": {            "id": "1234567890",            "name": "Example Brand",            "logoUrl": "https://cdn.example.com/pages/example-brand.png",            "facebookPageId": "1234567890",            "liveAdsCount": 42,            "reach30d": 152340,            "totalReach": 842100,            "countriesCount": 8,            "facebookLikes": 125000,            "instagramFollowers": 89000          },          "content": {            "title": "Summer Sale",            "body": "Up to 30% off selected products.",            "transcript": "Save 30% on every order.",            "callToAction": "Shop now",            "landingPageUrl": "https://example.com/products/summer-sale",            "landingPageDomain": "example.com",            "ctaDescription": "Free shipping on orders over $50.",            "ctaLinkDescription": "Shop the full collection"          },          "metrics": {            "reach": 152340,            "aggregatedReach": 284100,            "estimatedSpend": 4262,            "duplicates": 4,            "reachDelta1d": 1200,            "reachDelta7d": 8200,            "reachDelta30d": 38400          },          "audience": {            "targetedCountries": [              "US",              "FR"            ],            "mainCountry": "FR",            "gender": "all",            "ageMin": 18,            "ageMax": 65          },          "rank": {            "positionInPage": 3,            "currentRank": 12,            "rankDelta": -4,            "improvementPct": 0.25          },          "flags": {            "isEuAd": true,            "isLowReach": false,            "isMediaChanged": false,            "hasPartnerBadge": true          }        }      ],      "pagination": {        "page": 1,        "limit": 25,        "total": 235,        "totalPages": 10      }    }  },  "meta": {}}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns timeline-ready Meta ads for one active workspace brandtracker resolved from brandtracker.id. Timeline membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer
limit?integer
sortBy?string

Sort key for this request. Allowed values: newest, createdAt, longestRunning, reach, duplicates, adOrder, relevance.

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?string
createdBefore?string
minDaysRunning?integer
maxDaysRunning?integer
minDuplicates?integer
maxDuplicates?integer
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?number
maxSpend?number
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?number
maxSpendPerPage?number
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer
maxAge?integer
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?integer
maxFacebookLikes?integer
minInstagramFollowers?integer
maxInstagramFollowers?integer
minVideoDuration?number
maxVideoDuration?number
minDescriptionLength?integer
maxDescriptionLength?integer
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

startedAfter?string

Inclusive ad start-date lower bound.

startedBefore?string

Inclusive ad start-date upper bound.

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/timeline"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "id": "facebook_123456789",      "collationId": "3810635369204881",      "platform": "facebook",      "status": "active",      "createdAt": "2026-04-18T12:30:00.000Z",      "firstSeenAt": "2026-04-10T00:00:00.000Z",      "lastSeenAt": "2026-04-19T00:00:00.000Z",      "daysRunning": 9,      "media": {        "type": "video",        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"      },      "advertiser": {        "id": "1234567890",        "name": "Example Brand",        "logoUrl": "https://cdn.example.com/pages/example-brand.png",        "facebookPageId": "1234567890",        "liveAdsCount": 42,        "reach30d": 152340,        "totalReach": 842100,        "countriesCount": 8,        "facebookLikes": 125000,        "instagramFollowers": 89000      },      "content": {        "title": "Summer Sale",        "body": "Up to 30% off selected products.",        "transcript": "Save 30% on every order.",        "callToAction": "Shop now",        "landingPageUrl": "https://example.com/products/summer-sale",        "landingPageDomain": "example.com",        "ctaDescription": "Free shipping on orders over $50.",        "ctaLinkDescription": "Shop the full collection"      },      "metrics": {        "reach": 152340,        "aggregatedReach": 284100,        "estimatedSpend": 4262,        "duplicates": 4,        "reachDelta1d": 1200,        "reachDelta7d": 8200,        "reachDelta30d": 38400      },      "audience": {        "targetedCountries": [          "US",          "FR"        ],        "mainCountry": "FR",        "gender": "all",        "ageMin": 18,        "ageMax": 65      },      "rank": {        "positionInPage": 3,        "currentRank": 12,        "rankDelta": -4,        "improvementPct": 0.25      },      "flags": {        "isEuAd": true,        "isLowReach": false,        "isMediaChanged": false,        "hasPartnerBadge": true      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 235,    "totalPages": 10  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns total count and date bounds for the same filter membership used by the brandtracker timeline endpoint.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?string
createdBefore?string
minDaysRunning?integer
maxDaysRunning?integer
minDuplicates?integer
maxDuplicates?integer
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?number
maxSpend?number
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?number
maxSpendPerPage?number
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer
maxAge?integer
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?integer
maxFacebookLikes?integer
minInstagramFollowers?integer
maxInstagramFollowers?integer
minVideoDuration?number
maxVideoDuration?number
minDescriptionLength?integer
maxDescriptionLength?integer
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

startedAfter?string

Inclusive ad start-date lower bound.

startedBefore?string

Inclusive ad start-date upper bound.

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/timeline/metadata"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "totalCount": 235,    "earliestDate": "2026-04-01",    "latestDate": "2026-04-23"  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns creative-testing batches grouped by ad start date for one active workspace brandtracker resolved from brandtracker.id. Testing membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date. To keep response size and metering bounded, each batch returns at most 20 ads and exposes truncation metadata.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Batch page number. Pagination is by distinct ad start-date batches.

limit?integer

Number of distinct start-date batches to return. Each batch returns at most 20 ads.

status?string

Status filter for this request. Allowed values: all, active, inactive.

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

createdAfter?|
createdBefore?|
minDaysRunning?|
maxDaysRunning?|
minDuplicates?|
maxDuplicates?|
landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?|

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?|

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReach?|

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpm?number

CPM used to convert spend filters into reach thresholds.

minSpend?|
maxSpend?|
spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

minSpendPerPage?|
maxSpendPerPage?|
spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?|
maxAge?|
sex?string

Enum value accepted by this request. Allowed values: men, women, all.

minFacebookLikes?|
maxFacebookLikes?|
minInstagramFollowers?|
maxInstagramFollowers?|
minVideoDuration?|
maxVideoDuration?|
minDescriptionLength?|
maxDescriptionLength?|
linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

startedAfter?string

Inclusive ad start-date lower bound.

startedBefore?string

Inclusive ad start-date upper bound.

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/testing"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": [    {      "startDate": "2026-04-20",      "ads": [        {          "id": "facebook_123456789",          "collationId": "3810635369204881",          "platform": "facebook",          "status": "active",          "createdAt": "2026-04-18T12:30:00.000Z",          "firstSeenAt": "2026-04-10T00:00:00.000Z",          "lastSeenAt": "2026-04-19T00:00:00.000Z",          "daysRunning": 9,          "media": {            "type": "video",            "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",            "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"          },          "advertiser": {            "id": "1234567890",            "name": "Example Brand",            "logoUrl": "https://cdn.example.com/pages/example-brand.png",            "facebookPageId": "1234567890",            "liveAdsCount": 42,            "reach30d": 152340,            "totalReach": 842100,            "countriesCount": 8,            "facebookLikes": 125000,            "instagramFollowers": 89000          },          "content": {            "title": "Summer Sale",            "body": "Up to 30% off selected products.",            "transcript": "Save 30% on every order.",            "callToAction": "Shop now",            "landingPageUrl": "https://example.com/products/summer-sale",            "landingPageDomain": "example.com",            "ctaDescription": "Free shipping on orders over $50.",            "ctaLinkDescription": "Shop the full collection"          },          "metrics": {            "reach": 152340,            "aggregatedReach": 284100,            "estimatedSpend": 4262,            "duplicates": 4,            "reachDelta1d": 1200,            "reachDelta7d": 8200,            "reachDelta30d": 38400          },          "audience": {            "targetedCountries": [              "US",              "FR"            ],            "mainCountry": "FR",            "gender": "all",            "ageMin": 18,            "ageMax": 65          },          "rank": {            "positionInPage": 3,            "currentRank": 12,            "rankDelta": -4,            "improvementPct": 0.25          },          "flags": {            "isEuAd": true,            "isLowReach": false,            "isMediaChanged": false,            "hasPartnerBadge": true          }        }      ],      "adsReturned": 20,      "maxAdsPerBatch": 20,      "adsTruncated": false,      "runningCount": 1,      "isWinner": true,      "stats": {        "reach": {          "min": 1200,          "avg": 4200,          "max": 9800,          "total": 16800        },        "daysRunning": {          "min": 2,          "avg": 12,          "max": 31        },        "activeCount": 2,        "totalCount": 4,        "bestPerformerId": "facebook_123456789"      }    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 73,    "totalPages": 3  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns graph-ready Brandtracker time-series for ads launched, live ads history, and EU impression/spend deltas. Use period for rolling windows, or startDate/endDate for explicit ranges; do not combine period with date params.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

granularity?string

Bucket size for the returned graph data. Defaults to daily.

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date. Cannot be combined with period.

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided. Cannot be combined with period.

snapshotDate?string

Optional snapshot date. When provided with period, it anchors the rolling window; otherwise it is used as the effective end date.

period?string

Optional rolling window for the time-series. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with startDate or endDate; snapshotDate may anchor the window.

euOnly?boolean

When true, only EU-classified ads are counted for adsLaunched.

cpm?number

CPM used to estimate spend from EU impression deltas.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/time-series"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "data": {    "granularity": "daily",    "dateRange": {      "startDate": "2026-01-01",      "endDate": "2026-04-20"    },    "adsLaunched": [      {        "date": "2026-04-20",        "count": 12      }    ],    "liveAds": [      {        "date": "2026-04-20",        "count": 12      }    ],    "euImpressionsSpend": [      {        "date": "2026-04-20",        "impressions": 12450,        "cumulativeImpressions": 431200,        "estimatedSpend": 112.05      }    ],    "cpm": 9  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns graph-ready ad copy evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide adCopy for exact single-text mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

adCopy?string

Exact ad copy text to return as a single evolution series. Omit for global mode.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/ad-copy-evolution"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "dateRange": {    "startDate": "2026-01-01",    "endDate": "2026-04-20"  },  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  },  "data": [    {      "adCopy": "Turn your mornings into a ritual.",      "points": [        {          "date": "2026-04-20",          "recordedAt": "2026-04-20T12:30:00.000Z",          "activeAds": 12,          "totalAds": 48,          "euAds": 9,          "euActiveAds": 7,          "totalReach": 124500,          "percentNewAds": 18.5        }      ]    }  ]}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns graph-ready headline evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide headline for exact single-text mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

headline?string

Exact headline text to return as a single evolution series. Omit for global mode.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/headline-evolution"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "dateRange": {    "startDate": "2026-01-01",    "endDate": "2026-04-20"  },  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  },  "data": [    {      "headline": "The ritual your skin was waiting for",      "points": [        {          "date": "2026-04-20",          "recordedAt": "2026-04-20T12:30:00.000Z",          "activeAds": 12,          "totalAds": 48,          "euAds": 9,          "euActiveAds": 7,          "totalReach": 124500,          "percentNewAds": 18.5        }      ]    }  ]}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Returns graph-ready landing page evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide landingPage for exact single-page mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer
AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; V2 brandtracker ids from before the V3 cutover are also accepted.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

landingPage?string

Exact landing page URL to return as a single evolution series. Omit for global mode.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/brandtrackers/string/landing-page-evolution"
{  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",  "dateRange": {    "startDate": "2026-01-01",    "endDate": "2026-04-20"  },  "pagination": {    "page": 1,    "limit": 20,    "total": 128,    "totalPages": 7  },  "meta": {    "requestedSnapshotDate": "latest",    "resolvedSnapshotDate": "2026-04-23",    "dataFreshnessLagDays": 1,    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."  },  "data": [    {      "landingPage": "https://example.com/products/ritual-kit",      "points": [        {          "date": "2026-04-20",          "recordedAt": "2026-04-20T12:30:00.000Z",          "activeAds": 12,          "totalAds": 48,          "euAds": 9,          "euActiveAds": 7,          "totalReach": 124500,          "percentNewAds": 18.5        }      ]    }  ]}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}
{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}