Brandtrackers
List brandtrackers
Returns the workspace-scoped active brandtrackers attached to the authenticated public API workspace. The public identifier is spyders.uuid.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Query Parameters
11 <= value251 <= value <= 100ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.
date-timeCase-insensitive contains match against brandtracker name.
length <= 200Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.
"newAdsLastDay" | "newAdsLast7Days" | "newAdsLast30Days" | "activeAds" | "totalTraffic" | "name" | "createdAt"Folder ids. Repeated query params and comma-separated values are both accepted.
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://api.trendtrack.io/v1/brandtrackers"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
"name": "Example Brand",
"facebookPageId": "61554990830184",
"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"
]
}
]
}
}
}List brandtracker folders
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 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://api.trendtrack.io/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"
]
}
]
}
}
}List brandtrackers in a folder
Returns the workspace-scoped active brandtrackers assigned to the requested folder. This is equivalent to /v1/brandtrackers?folderIds=:folderId.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Workspace brandtracker folder id.
1 <= valueQuery Parameters
11 <= value251 <= value <= 100ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.
date-timeCase-insensitive contains match against brandtracker name.
length <= 200Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.
"newAdsLastDay" | "newAdsLast7Days" | "newAdsLast30Days" | "activeAds" | "totalTraffic" | "name" | "createdAt"Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/folders/1/brandtrackers"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
"name": "Example Brand",
"facebookPageId": "61554990830184",
"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"
]
}
]
}
}
}Get a brandtracker
Returns the detail payload for one active workspace brandtracker resolved from spyders.uuid.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier backed by spyders.uuid.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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",
"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"
]
}
]
}
}
}List brandtracker snapshot dates
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier backed by spyders.uuid.
Query Parameters
Pagination page number. Defaults to 1.
11 <= valueMaximum number of snapshot dates to return. Defaults to 100.
1001 <= value <= 365Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}List brandtracker ads
Returns the Meta ads for one active workspace brandtracker resolved from spyders.uuid to fb_page_id. The response reuses the public ad summary shape.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier backed by spyders.uuid.
Query Parameters
11 <= value251 <= value <= 100Sort key. The adOrder value also accepts ad_order and ad-order aliases.
"newest" | "createdAt" | "longestRunning" | "reach" | "duplicates" | "adOrder" | "relevance"Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes for ad copy descriptions.
Comma-separated country include/exclude filters.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
When true, keep only partnership ads. When false, keep only non-partnership ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/ads"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}List brandtracker partnership ads
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier backed by spyders.uuid.
Query Parameters
11 <= value251 <= value <= 100Sort key. The adOrder value also accepts ad_order and ad-order aliases.
"newest" | "createdAt" | "longestRunning" | "reach" | "duplicates" | "adOrder" | "relevance"Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes for ad copy descriptions.
Comma-separated country include/exclude filters.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
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://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/partnership-ads"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Count brandtracker partnership ads
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier backed by spyders.uuid.
Query Parameters
Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes for ad copy descriptions.
Comma-separated country include/exclude filters.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
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://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker hooks
Returns grouped hook analytics for the requested brandtracker using the authenticated workspace as the only access scope.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional hook sorting. Defaults to usageCount.
"usageCount" | "longestRunning" | "totalImpressions" | "firstUsedAt" | "lastUsedAt"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker transcripts
Returns grouped transcript/script analytics for the requested brandtracker using the authenticated workspace as the only access scope.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional transcript sorting. Defaults to usageCount.
"usageCount" | "longestRunning" | "totalImpressions" | "firstUsedAt" | "lastUsedAt"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker headlines
Returns grouped headline analytics for the requested brandtracker.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional headline sorting. Defaults to usageCount.
"usageCount" | "longestRunning"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker ad copies
Returns grouped ad copy analytics for the requested brandtracker.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional ad copy sorting. Defaults to usageCount.
"usageCount" | "longestRunning"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker landing pages
Returns grouped landing page analytics for the requested brandtracker, including detected technologies when available.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional landing page sorting. Defaults to usageCount.
"usageCount" | "longestRunning" | "totalImpressions"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get normalized brandtracker landing pages
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional normalized landing page sorting. Defaults to usageCount.
"usageCount" | "activeAdsCount"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker creatives
Returns paginated creative analytics for the requested brandtracker.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional creatives sorting. Defaults to firstSeenAt.
"firstSeenAt" | "daysRunning" | "duplicates"Optional media type filter. Defaults to all.
"all" | "image" | "video"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker partners
Returns paginated partnership analytics for the requested brandtracker.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional sort order. Defaults to desc.
"asc" | "desc"Optional snapshot anchor date (YYYY-MM-DD or latest). When provided, the requested window is evaluated against that snapshot date; use latest to resolve the latest ready snapshot.
Optional partners sorting. Defaults to activeAds.
"activeAds" | "launchDate" | "reach" | "estimatedSpend"Optional CPM used to estimate spend from reach. Defaults to 9.
90 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker media mix
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseOptional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker demography
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
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.
trueOptional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
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.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get top ads
Top-ads 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 honored for non-rank-delta requests; rank-delta sort keys encode their own time window and cannot be combined with explicit period or snapshotDate.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Optional EU-only filter. When true, only EU-classified Facebook ads are included.
falseSort key for top ads. Use currentRank for the current Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings. Rank-delta sorts cannot be combined with explicit period or snapshotDate.
"currentRank" | "rankDelta" | "rankDelta7d" | "rankDelta14d" | "rankDelta30d" | "reach" | "reachDelta1d" | "reachDelta7d" | "reachDelta30d" | "daysRunning" | "duplicates"When true, include inactive ads for the supported EU all-time variant only (euOnly=true, period=total, no snapshotDate). Other combinations remain active-only.
falseOptional rolling top-ads period honored for non-rank-delta requests. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total. Rank-delta sorts encode their own time window and cannot be combined with explicit period.
"today" | "yesterday" | "last1d" | "last7d" | "last14d" | "last30d" | "total"Optional snapshot date honored for non-rank-delta top-ads requests. Use latest to resolve the latest ready snapshot. When period=today, the latest ready snapshot is used even if snapshotDate is provided. Rank-delta sorts encode their own time window and cannot be combined with snapshotDate.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/top-ads"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"ad": {
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Get brandtracker ad rank compatibility data
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.
"last7d" | "last14d" | "last30d" | "7d" | "14d" | "30d"Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.
"rankDelta" | "currentRank" | "rank_delta" | "current_rank"Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.
Optional maximum current rank filter. Only ads at or above this current rank are returned.
1 <= valueMinimum positive rank improvement required for an ad to be returned. Defaults to 1.
11 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/ad-rank"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"ad": {
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Get brandtracker scaling ads compatibility data
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number. Defaults to 1.
11 <= valueMaximum number of items to return. Defaults to 20.
201 <= value <= 50Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.
"last7d" | "last14d" | "last30d" | "7d" | "14d" | "30d"Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.
"rankDelta" | "currentRank" | "rank_delta" | "current_rank"Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.
Optional maximum current rank filter. Only ads at or above this current rank are returned.
1 <= valueMinimum positive rank improvement required for an ad to be returned. Defaults to 1.
11 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/scaling-ads"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"ad": {
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Get brandtracker ad copy evolution
Returns graph-ready ad copy evolution series for one active workspace brandtracker resolved from spyders.uuid. Provide adCopy for exact single-text mode, or omit it to page through bounded global series ranked by active ads.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number for global mode. Exact mode always returns at most one series.
11 <= valueNumber of series to return in global mode. Exact mode costs and returns one series.
101 <= value <= 25Inclusive start date. Defaults to 365 days before the effective end date.
dateInclusive end date. Defaults to today unless snapshotDate is provided.
dateOptional snapshot date (YYYY-MM-DD or latest). When provided, it is used as the effective end date; use latest to resolve the latest ready snapshot.
Exact ad copy text to return as a single evolution series. Omit for global mode.
length <= 5000Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker headline evolution
Returns graph-ready headline evolution series for one active workspace brandtracker resolved from spyders.uuid. Provide headline for exact single-text mode, or omit it to page through bounded global series ranked by active ads.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number for global mode. Exact mode always returns at most one series.
11 <= valueNumber of series to return in global mode. Exact mode costs and returns one series.
101 <= value <= 25Inclusive start date. Defaults to 365 days before the effective end date.
dateInclusive end date. Defaults to today unless snapshotDate is provided.
dateOptional snapshot date (YYYY-MM-DD or latest). When provided, it is used as the effective end date; use latest to resolve the latest ready snapshot.
Exact headline text to return as a single evolution series. Omit for global mode.
length <= 1000Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker landing page evolution
Returns graph-ready landing page evolution series for one active workspace brandtracker resolved from spyders.uuid. Provide landingPage for exact single-page mode, or omit it to page through bounded global series ranked by active ads.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Pagination page number for global mode. Exact mode always returns at most one series.
11 <= valueNumber of series to return in global mode. Exact mode costs and returns one series.
101 <= value <= 25Inclusive start date. Defaults to 365 days before the effective end date.
dateInclusive end date. Defaults to today unless snapshotDate is provided.
dateOptional snapshot date (YYYY-MM-DD or latest). When provided, it is used as the effective end date; use latest to resolve the latest ready snapshot.
Exact landing page URL to return as a single evolution series. Omit for global mode.
length <= 2048Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}Get brandtracker time-series
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Bucket size for the returned graph data. Defaults to daily.
"daily" | "weekly" | "monthly"Inclusive start date. Defaults to 365 days before the effective end date. Cannot be combined with period.
dateInclusive end date. Defaults to today unless snapshotDate is provided. Cannot be combined with period.
dateOptional snapshot date (YYYY-MM-DD or latest). When provided with period, it anchors the rolling window; otherwise it is used as the effective end date. Use latest to resolve the latest ready snapshot.
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.
"today" | "yesterday" | "1d" | "7d" | "14d" | "30d" | "90d" | "365d"When true, only EU-classified ads are counted for adsLaunched.
falseCPM used to estimate spend from EU impression deltas.
90.01 <= value <= 10000Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}List brandtracker timeline ads
Returns timeline-ready Meta ads for one active workspace brandtracker resolved from spyders.uuid. Timeline membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
11 <= value501 <= value <= 100Sort key for this request. Allowed values: newest, createdAt, longestRunning, reach, duplicates, adOrder, relevance.
"newest" | "createdAt" | "longestRunning" | "reach" | "duplicates" | "adOrder" | "relevance"Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.
Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
When true, keep only partnership ads. When false, keep only non-partnership ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
Inclusive ad start-date lower bound.
dateInclusive ad start-date upper bound.
dateInclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.
dateInclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.
dateResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/timeline"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Get brandtracker timeline metadata
Returns total count and date bounds for the same filter membership used by the brandtracker timeline endpoint.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.
Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
When true, keep only partnership ads. When false, keep only non-partnership ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
Inclusive ad start-date lower bound.
dateInclusive ad start-date upper bound.
dateInclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.
dateInclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.
dateResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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"
]
}
]
}
}
}List brandtracker creative testing batches
Returns creative-testing batches grouped by ad start date for one active workspace brandtracker resolved from spyders.uuid. 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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Batch page number. Pagination is by distinct ad start-date batches.
11 <= valueNumber of distinct start-date batches to return. Each batch returns at most 20 ads.
251 <= value <= 50Status filter for this request. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Enum value accepted by this request. Allowed values: all, image, video.
"all" | "image" | "video"Keyword search terms. Repeated query params and comma-separated values are both accepted.
Enum value accepted by this request. Allowed values: any, all.
"any" | "all"date-timedate-time0 <= value0 <= value0 <= value0 <= valueLanding page URLs. Repeated query params and comma-separated values are both accepted.
Ad languages. Repeated query params and comma-separated values are both accepted.
Call-to-action labels. Repeated query params and comma-separated values are both accepted.
12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.
Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.
Main ad countries. Repeated query params and comma-separated values are both accepted.
When true, keep only ads flagged as EU ads.
When true, keep only partnership ads. When false, keep only non-partnership ads.
Partner identifiers. Repeated query params and comma-separated values are both accepted.
Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueMaximum ad reach threshold. Backed by the internal reach/impressions analytics field.
0 <= valueCPM used to convert spend filters into reach thresholds.
90.01 <= value0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"0 <= value0 <= valueEnum value accepted by this request. Allowed values: total, last24h, last7d, last30d.
"total" | "last24h" | "last7d" | "last30d"When true, hides ads flagged as low reach.
0 <= value0 <= valueEnum value accepted by this request. Allowed values: men, women, all.
"men" | "women" | "all"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueLinked domain filter. URLs are normalized to their hostname before validation.
Rank trend filters. Repeated query params and comma-separated values are both accepted.
Optional snapshot date (YYYY-MM-DD or latest). Use latest to resolve the latest ready snapshot.
Inclusive ad start-date lower bound.
dateInclusive ad start-date upper bound.
dateInclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.
dateInclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.
dateResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/testing"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"startDate": "2026-04-20",
"ads": [
{
"id": "facebook_123456789",
"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": "US",
"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"
]
}
]
}
}
}Get brandtracker overview
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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public brandtracker identifier. This endpoint resolves the resource from spyders.uuid inside the authenticated workspace.
Query Parameters
Optional EU-only filter forwarded to graph, media mix, landing pages, and top ads sections where supported.
falseSnapshot date for dashboard time travel. Use YYYY-MM-DD or latest.
CPM used to estimate spend in the graph section.
90.01 <= value <= 10000Bucket size for the graph section. Defaults to daily.
"daily" | "weekly" | "monthly"Inclusive graph start date. Cannot be combined with timeSeriesPeriod.
dateInclusive graph end date. Cannot be combined with timeSeriesPeriod.
dateOptional 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.
"today" | "yesterday" | "1d" | "7d" | "14d" | "30d" | "90d" | "365d"Time window for top landing pages. Defaults to live for dashboard-style current overview.
"live" | "last24h" | "last3d" | "last7d" | "last30d" | "last3m" | "last6m" | "last1y"Maximum number of top landing pages to return. Defaults to 5.
51 <= value <= 20Maximum number of top ads to return. Defaults to 5.
51 <= value <= 20Maximum number of ads preview items to return. Defaults to 10.
101 <= value <= 50Optional top ads sorting. Defaults to reach when euOnly=true, otherwise daysRunning.
"currentRank" | "rankDelta" | "rankDelta7d" | "rankDelta14d" | "rankDelta30d" | "reach" | "reachDelta1d" | "reachDelta7d" | "reachDelta30d" | "daysRunning" | "duplicates"Optional top ads period. Supports today, yesterday, last1d, last7d, last14d, last30d, and total. Defaults to total.
"today" | "yesterday" | "last1d" | "last7d" | "last14d" | "last30d" | "total"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/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",
"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": "US",
"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",
"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": "US",
"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"
]
}
]
}
}
}