Advertisers
List advertisers
Returns the lightweight public advertisers collection. This endpoint stays intentionally simple and focuses on brand/domain search, pagination, ordering, and stable scalar filters. Use POST /v1/advertisers/query for the advanced discovery surface.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Query Parameters
Optional advertiser search keywords. Repeated query params and comma-separated values are both accepted.
Simple search strategy for the advertisers collection. Use POST /v1/advertisers/query for advanced text resolution modes.
"brand" | "domain"How multiple search keywords should combine. Defaults to any.
"any" | "all"Primary sort key for advertiser discovery. Defaults to relevance.
"relevance" | "newest" | "activeAds" | "newAds" | "euAdsShare" | "reach" | "reach14d" | "followers"Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.
"asc" | "desc"Pagination offset. Defaults to 0.
00 <= valueMaximum number of advertisers to return. Defaults to 20.
201 <= value <= 100Inclusive lower bound for the Facebook page creation date filter.
dateInclusive upper bound for the Facebook page creation date filter.
date0 <= value0 <= valueEnum value accepted by this request. Allowed values: current, last24h, last7d, last14d, last30d.
"current" | "last24h" | "last7d" | "last14d" | "last30d"0 <= value0 <= value0 <= value0 <= value0 <= value0 <= valueTime window accepted by this request. Allowed values: last24h, last7d, last14d, last30d, last90d.
"last24h" | "last7d" | "last14d" | "last30d" | "last90d"Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.
0 <= valueMaximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.
0 <= valueReach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: last24h, last7d, last14d, last30d, last90d, total.
"last24h" | "last7d" | "last14d" | "last30d" | "last90d" | "total"Enum value accepted by this request. Allowed values: influencer, brand.
Simple advertiser category filter. Repeated query params and comma-separated values are both accepted. Equivalent to POST /v1/advertisers/query pageNiches.among.
Filter by indexed linked-site Shopify technology. no means no indexed Shopify technology is present for the advertiser.
"yes" | "no" | "all"Enum value accepted by this request. Allowed values: male, female, all.
"male" | "female" | "all"Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/advertisers"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "61554990830184",
"platform": "facebook",
"facebookPageId": "61554990830184",
"name": "Example Brand",
"logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
"profile": {
"likes": 125000,
"instagramFollowers": 89000,
"createdAt": "2019-01-04T00:00:00.000Z"
},
"advertising": {
"activeAds": 12,
"reach30d": 452000
},
"lastAds": [
{
"id": "facebook:123456789",
"mediaUrl": "https://medias.trendtrack.io/facebook/media/ad-1.mp4",
"thumbnailUrl": "https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"
}
],
"mainLandingPages": [
{
"landingPage": "https://example.com/products/summer",
"screenshotUrl": "https://medias.trendtrack.io/landing-pages/summer.jpg"
}
]
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 128
},
"meta": {
"isTruncated": false
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}Query advertisers
Returns the advanced public advertisers query surface. This endpoint supports the current richer advertiser discovery filters through a structured public camelCase contract while keeping the response aligned with the standard public advertiser summary shape. categoryIds is a shorthand for pageNiches.among; send categoryIds or pageNiches (not both). Empty JSON bodies are valid and use defaults.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.trendtrack.io/v1/advertisers/query" \ -H "Content-Type: application/json" \ -d '{ "search": [ "athleisure" ], "searchType": "brand", "sortBy": "reach", "order": "desc", "adsTimePeriod": "last7d", "minActiveAds": 10, "reachPeriod": "last14d", "minReach": 50000, "categoryIds": [ 254 ], "pageType": [ "brand" ], "limit": 20, "offset": 0 }'{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "61554990830184",
"platform": "facebook",
"facebookPageId": "61554990830184",
"name": "Example Brand",
"logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
"profile": {
"likes": 125000,
"instagramFollowers": 89000,
"createdAt": "2019-01-04T00:00:00.000Z"
},
"advertising": {
"activeAds": 12,
"reach30d": 452000
},
"lastAds": [
{
"id": "facebook:123456789",
"mediaUrl": "https://medias.trendtrack.io/facebook/media/ad-1.mp4",
"thumbnailUrl": "https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"
}
],
"mainLandingPages": [
{
"landingPage": "https://example.com/products/summer",
"screenshotUrl": "https://medias.trendtrack.io/landing-pages/summer.jpg"
}
]
}
],
"pagination": {
"limit": 20,
"offset": 0,
"total": 128
},
"meta": {
"isTruncated": false
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_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 ads for an advertiser
Returns a paginated list of ads for the requested page-centric advertiser. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public advertiser identifier. Current MVP uses the Facebook page id directly.
Query Parameters
251 <= value <= 10000 <= valueFilter ads by activity status. Allowed values: all, active, inactive.
"all" | "active" | "inactive"Filter ads by creative media type. Allowed values: all, image, video.
"all" | "image" | "video"Sort key for advertiser ads. reach uses the public reach/impressions metric; no impressions alias is accepted on this endpoint.
"newest" | "createdAt" | "longestRunning" | "reach" | "duplicates"Sort direction. Allowed values: asc, desc.
"asc" | "desc"Optional CPM override used to compute estimated spend in the ads response.
90 <= valueResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/advertisers/61554990830184/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": {
"limit": 25,
"offset": 0,
"total": 128
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_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 advertiser detail
Returns the page-centric advertiser detail. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public advertiser identifier. Current MVP uses the Facebook page id directly.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/advertisers/61554990830184"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": {
"id": "61554990830184",
"platform": "facebook",
"facebookPageId": "61554990830184",
"name": "Example Brand",
"logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
"profile": {
"likes": 125000,
"instagramFollowers": 89000,
"createdAt": "2019-01-04T00:00:00.000Z"
},
"linkedShops": [
{
"shopId": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
"domain": "example.com",
"name": "Example Shop",
"isPrimary": true
}
],
"advertising": {
"activeAds": 12,
"reach30d": 452000,
"countryDistribution": [
{
"countryCode": "US",
"share": 0.42
}
]
},
"lastAds": [
{
"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
}
}
]
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Provide an API key using Authorization: Bearer <api_key>.",
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"details": {
"validationErrors": [
{
"field": "query-string.limit",
"location": "query-string",
"expected": [
"limit must not be greater than 100"
]
}
]
}
}
}