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.

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.

Value in"brand" | "domain" | "adCopy" | "websiteCopy" | "urlContains"

keywordMode?string

Value in"any" | "all"

sortBy?string

order?string

Value in"asc" | "desc"

offset?number

Range0 <= value

limit?number

Range1 <= value <= 100

minFbPageCreationDate?string

maxFbPageCreationDate?string

minActiveAds?number

Range0 <= value

maxActiveAds?number

Range0 <= value

adsTimePeriod?string

Value in"current" | "last24h" | "last7d" | "last14d" | "last30d"

minFacebookLikes?number

Range0 <= value

maxFacebookLikes?number

Range0 <= value

minInstagramFollowers?number

Range0 <= value

maxInstagramFollowers?number

Range0 <= value

minAdsLaunched?number

Range0 <= value

maxAdsLaunched?number

Range0 <= value

adsLaunchedPeriod?string

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d"

minReach?number

Range0 <= value

maxReach?number

Range0 <= value

reachPeriod?string

minSpendPerPage?number

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

Range0 <= value

maxSpendPerPage?number

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

Range0 <= value

spendPerPagePeriod?string

cpm?number

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

Range0 <= value

minReachPerPage?number

Minimum reach-per-page filter.

Range0 <= value

maxReachPerPage?number

Maximum reach-per-page filter.

Range0 <= value

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

Value in"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<>

pageNiches?

Page niche selection split into main, among, and exclude category ids.

minPartnershipPercentage?number

Range0 <= value <= 100

shopifyLinked?string

Value in"yes" | "no" | "all"

gender?string

Value in"male" | "female" | "all"

Response Body

`application/json`

curl -X POST "https://loading/v1/advertisers/query" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "61554990830184",
      "platform": "facebook",
      "facebookPageId": "61554990830184",
      "name": "Example Brand",
      "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "profile": {
        "likes": 125000,
        "instagramFollowers": 89000,
        "createdAt": "2020-05-03T12:00:00.000Z"
      },
      "advertising": {
        "activeAds": 12,
        "reach30d": 452000
      }
    }
  ],
  "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"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc"
  }
}

Authorization

Request Body

Response Body

200application/json

401application/json

403application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`