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

AuthorizationBearer <token>

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

In: header

Query Parameters

search?array<string>

Optional advertiser search keywords. Repeated query params and comma-separated values are both accepted.

searchType?string

Simple search strategy for the advertisers collection. Use POST /v1/advertisers/query for advanced text resolution modes.

keywordMode?string

How multiple search keywords should combine. Defaults to any.

sortBy?string

Primary sort key for advertiser discovery. Defaults to relevance.

order?string

Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.

offset?integer

Pagination offset. Defaults to 0.

limit?integer

Maximum number of advertisers to return. Defaults to 20.

minFbPageCreationDate?string

Inclusive lower bound for the Facebook page creation date filter.

maxFbPageCreationDate?string

Inclusive upper bound for the Facebook page creation date filter.

minActiveAds?integer

maxActiveAds?integer

adsTimePeriod?string

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

minFacebookLikes?integer

maxFacebookLikes?integer

minInstagramFollowers?integer

maxInstagramFollowers?integer

minAdsLaunched?integer

maxAdsLaunched?integer

adsLaunchedPeriod?string

Time window accepted by this request. Allowed values: last24h, last7d, last14d, last30d, last90d.

minReach?integer

Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

maxReach?integer

Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

reachPeriod?string

Reach/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.

pageType?array<>

Enum value accepted by this request. Allowed values: influencer, brand.

categoryIds?array<>

Google category facet ids matched through linked websites' website_overview.google_categories. Repeated query params and comma-separated values are both accepted.

shopifyLinked?string

Filter by indexed linked-site Shopify technology. no means no indexed Shopify technology is present for the advertiser.

gender?string

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

Response Body

`application/json`

curl -X GET "https://example.com/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

AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

search?array<string>

searchType?string

Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search.

keywordMode?string

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

sortBy?string

Sort key for this request. Allowed values: relevance, newest, activeAds, newAds, euAdsShare, reach, reach14d, followers.

order?string

Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.

offset?number

limit?number

minFbPageCreationDate?string

maxFbPageCreationDate?string

minActiveAds?number

maxActiveAds?number

adsTimePeriod?string

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

minFacebookLikes?number

maxFacebookLikes?number

minInstagramFollowers?number

maxInstagramFollowers?number

minAdsLaunched?number

maxAdsLaunched?number

adsLaunchedPeriod?string

Time window accepted by this request. Allowed values: last24h, last7d, last14d, last30d, last90d.

minReach?number

Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

maxReach?number

Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

reachPeriod?string

minSpendPerPage?number

Minimum estimated spend per page. Converted internally through CPM and reach/impressions fields.

maxSpendPerPage?number

Maximum estimated spend per page. Converted internally through CPM and reach/impressions fields.

spendPerPagePeriod?string

cpm?number

CPM used to convert spend filters into reach/impressions-based ES ranges.

minReachPerPage?number

Minimum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

maxReachPerPage?number

Maximum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

reachPerPagePeriod?string

adLanguage?array<string>

technologies?array<string>

adCountries?

Countries where the advertiser is distributing ads. Uses ISO 3166-1 alpha-2 country codes.

mainCountries?array<string>

Primary countries to match.

countryFilterMode?string

Enum value accepted by this request. Allowed values: reach, adCount.

adsGrowth?

Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.

pageReachGrowth?

Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.

ageRanges?array<string>

pageType?array<>

Enum value accepted by this request. Allowed values: influencer, brand.

categoryIds?array<number>

Google category facet ids matched through linked websites' website_overview.google_categories.

pageNiches?

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.

minPartnershipPercentage?number

shopifyLinked?string

Filter by indexed linked-site Shopify technology. no means no indexed Shopify technology is present for the advertiser.

gender?string

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

Response Body

`application/json`

curl -X POST "https://example.com/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

AuthorizationBearer <token>

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

In: header

Path Parameters

advertiserId*string

Public advertiser identifier. Current MVP uses the Facebook page id directly.

Query Parameters

limit?integer

offset?integer

status?string

Filter ads by activity status. Allowed values: all, active, inactive.

mediaType?string

Filter ads by creative media type. Allowed values: all, image, video.

sortBy?string

Sort key for advertiser ads. reach uses the public reach/impressions metric; no impressions alias is accepted on this endpoint.

order?string

Sort direction. Allowed values: asc, desc.

cpm?integer

Optional CPM override used to compute estimated spend in the ads response.

Response Body

`application/json`

curl -X GET "https://example.com/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

AuthorizationBearer <token>

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

In: header

Path Parameters

advertiserId*string

Public advertiser identifier. Current MVP uses the Facebook page id directly.

Response Body

`application/json`

curl -X GET "https://example.com/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"          ]        }      ]    }  }}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`