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.
Google category facet ids matched through linked websites' website_overview.google_categories. Repeated query params and comma-separated values are both accepted.
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 uses linked websites' google_categories; pageNiches remains an advanced legacy page-niche filter. 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.
Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search.
"brand" | "domain" | "adCopy" | "websiteCopy" | "urlContains"Enum value accepted by this request. Allowed values: any, all.
"any" | "all"Sort key for this request. Allowed values: relevance, newest, activeAds, newAds, euAdsShare, reach, reach14d, followers.
"relevance" | "newest" | "activeAds" | "newAds" | "euAdsShare" | "reach" | "reach14d" | "followers"Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.
"asc" | "desc"0 <= value1 <= value <= 1000 <= 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"Minimum estimated spend per page. Converted internally through CPM and reach/impressions fields.
0 <= valueMaximum estimated spend per page. Converted internally through CPM and reach/impressions fields.
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"CPM used to convert spend filters into reach/impressions-based ES ranges.
0 <= valueMinimum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.
0 <= valueMaximum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.
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"Countries where the advertiser is distributing ads. Uses ISO 3166-1 alpha-2 country codes.
Primary countries to match.
Enum value accepted by this request. Allowed values: reach, adCount.
"reach" | "adCount"Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.
Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.
Enum value accepted by this request. Allowed values: influencer, brand.
Google category facet ids matched through linked websites' website_overview.google_categories.
Not supported: advertiser page niches are not indexed, so any non-empty selection is rejected with 400 unsupported_filter. Use categoryIds, which matches linked websites via google_categories.
0 <= value <= 100Filter 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 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", "collationId": "3810635369204881", "platform": "facebook", "status": "active", "createdAt": "2026-04-18T12:30:00.000Z", "firstSeenAt": "2026-04-10T00:00:00.000Z", "lastSeenAt": "2026-04-19T00:00:00.000Z", "daysRunning": 9, "media": { "type": "video", "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg", "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4" }, "advertiser": { "id": "1234567890", "name": "Example Brand", "logoUrl": "https://cdn.example.com/pages/example-brand.png", "facebookPageId": "1234567890", "liveAdsCount": 42, "reach30d": 152340, "totalReach": 842100, "countriesCount": 8, "facebookLikes": 125000, "instagramFollowers": 89000 }, "content": { "title": "Summer Sale", "body": "Up to 30% off selected products.", "transcript": "Save 30% on every order.", "callToAction": "Shop now", "landingPageUrl": "https://example.com/products/summer-sale", "landingPageDomain": "example.com", "ctaDescription": "Free shipping on orders over $50.", "ctaLinkDescription": "Shop the full collection" }, "metrics": { "reach": 152340, "aggregatedReach": 284100, "estimatedSpend": 4262, "duplicates": 4, "reachDelta1d": 1200, "reachDelta7d": 8200, "reachDelta30d": 38400 }, "audience": { "targetedCountries": [ "US", "FR" ], "mainCountry": "FR", "gender": "all", "ageMin": 18, "ageMax": 65 }, "rank": { "positionInPage": 3, "currentRank": 12, "rankDelta": -4, "improvementPct": 0.25 }, "flags": { "isEuAd": true, "isLowReach": false, "isMediaChanged": false, "hasPartnerBadge": true } } ], "pagination": { "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", "collationId": "3810635369204881", "platform": "facebook", "status": "active", "createdAt": "2026-04-18T12:30:00.000Z", "firstSeenAt": "2026-04-10T00:00:00.000Z", "lastSeenAt": "2026-04-19T00:00:00.000Z", "daysRunning": 9, "media": { "type": "video", "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg", "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4" }, "advertiser": { "id": "1234567890", "name": "Example Brand", "logoUrl": "https://cdn.example.com/pages/example-brand.png", "facebookPageId": "1234567890", "liveAdsCount": 42, "reach30d": 152340, "totalReach": 842100, "countriesCount": 8, "facebookLikes": 125000, "instagramFollowers": 89000 }, "content": { "title": "Summer Sale", "body": "Up to 30% off selected products.", "transcript": "Save 30% on every order.", "callToAction": "Shop now", "landingPageUrl": "https://example.com/products/summer-sale", "landingPageDomain": "example.com", "ctaDescription": "Free shipping on orders over $50.", "ctaLinkDescription": "Shop the full collection" }, "metrics": { "reach": 152340, "aggregatedReach": 284100, "estimatedSpend": 4262, "duplicates": 4, "reachDelta1d": 1200, "reachDelta7d": 8200, "reachDelta30d": 38400 }, "audience": { "targetedCountries": [ "US", "FR" ], "mainCountry": "FR", "gender": "all", "ageMin": 18, "ageMax": 65 }, "rank": { "positionInPage": 3, "currentRank": 12, "rankDelta": -4, "improvementPct": 0.25 }, "flags": { "isEuAd": true, "isLowReach": false, "isMediaChanged": false, "hasPartnerBadge": true } } ] }}{ "error": { "code": "missing_api_key", "message": "Provide an API key using Authorization: Bearer <api_key>.", "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "details": { "validationErrors": [ { "field": "query-string.limit", "location": "query-string", "expected": [ "limit must not be greater than 100" ] } ] } }}{ "error": { "code": "missing_api_key", "message": "Provide an API key using Authorization: Bearer <api_key>.", "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "details": { "validationErrors": [ { "field": "query-string.limit", "location": "query-string", "expected": [ "limit must not be greater than 100" ] } ] } }}{ "error": { "code": "missing_api_key", "message": "Provide an API key using Authorization: Bearer <api_key>.", "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "details": { "validationErrors": [ { "field": "query-string.limit", "location": "query-string", "expected": [ "limit must not be greater than 100" ] } ] } }}{ "error": { "code": "missing_api_key", "message": "Provide an API key using Authorization: Bearer <api_key>.", "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "details": { "validationErrors": [ { "field": "query-string.limit", "location": "query-string", "expected": [ "limit must not be greater than 100" ] } ] } }}{ "error": { "code": "missing_api_key", "message": "Provide an API key using Authorization: Bearer <api_key>.", "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "details": { "validationErrors": [ { "field": "query-string.limit", "location": "query-string", "expected": [ "limit must not be greater than 100" ] } ] } }}