Query ads

Returns the advanced public ads query surface. This endpoint supports the full current ads filtering set through a public camelCase contract with structured JSON for advanced growth, country, market, and ranking filters while keeping the response aligned with the standard public ad 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>

Optional list of search terms used by the advanced ads query engine.

searchType?string

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

keywordMode?string

Value in"any" | "all"

sort?string

sortOrder?string

Value in"asc" | "desc"

page?number

Range1 <= value

limit?number

Range1 <= value <= 100

platforms?array<>

mediaType?string

Value in"image" | "video"

minDateAds?string

Formatdate-time

maxDateAds?string

Formatdate-time

minFbPageCreationDate?string

Formatdate-time

maxFbPageCreationDate?string

Formatdate-time

minLastSeenDate?string

Formatdate-time

maxLastSeenDate?string

Formatdate-time

minDaysRunning?number

Range0 <= value

maxDaysRunning?number

Range0 <= value

status?string

Value in"active" | "inactive" | "all"

minDuplicates?number

Range0 <= value

maxDuplicates?number

Range0 <= value

minDescriptionLength?number

Range0 <= value

maxDescriptionLength?number

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

maxAdOrder?number

Range1 <= value

adRankMode?string

Value in"percentile" | "rank"

adRankBasis?string

Value in"current" | "alltime"

maxAdRankValue?number

Range1 <= value

growthRank?

Advanced rank trend filter. Uses OR groups (anyOf) made of AND-ed rules (all).

adLanguage?array<string>

cta?array<string>

minReach?number

Minimum reach threshold. Backed by the internal reach/impressions analytics fields.

Range0 <= value

maxReach?number

Maximum reach threshold. Backed by the internal reach/impressions analytics fields.

Range0 <= value

minAge?number

Range0 <= value

maxAge?number

Range0 <= value

sex?string

Value in"men" | "women" | "all"

adCountries?

Countries where the ad is distributed. Uses ISO 3166-1 alpha-2 country codes.

mainCountries?array<string>

spender?string

Value in"big-spender" | "rising-star" | "brandtracker"

partners?boolean

minTraffic?number

Range0 <= value

maxTraffic?number

Range0 <= value

growth?

Traffic growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.

minAds?number

Range0 <= value

maxAds?number

Range0 <= value

adsGrowth?

Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.

pageReachGrowth?

Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).

adReachGrowth?

Ad reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).

niches?array<number>

minProducts?number

Range0 <= value

maxProducts?number

Range0 <= value

minBestSellerPrice?number

Range0 <= value

maxBestSellerPrice?number

Range0 <= value

themes?array<string>

pixels?array<string>

excludePixels?array<string>

languages?array<string>

currencies?array<string>

shopifyApps?array<number>

excludeShopifyApps?array<number>

adsTimePeriod?string

Value in"last24h" | "last7d" | "last30d"

minDate?string

Formatdate-time

maxDate?string

Formatdate-time

creationCountry?

Advertiser creation country filter using ISO 3166-1 alpha-2 country codes.

market?

Market filter grouped by primary markets, secondary markets, and excluded markets.

shopifyPlus?string

Value in"plus" | "non-plus" | "all"

minTrustpilotScore?number

Range0 <= value

maxTrustpilotScore?number

Range0 <= value

minTrustpilotReviews?number

Range0 <= value

maxTrustpilotReviews?number

Range0 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

cpm?number

Range0 <= value

spendPeriod?string

Value in"total" | "last24h" | "last7d" | "last30d"

reachPeriod?string

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Value in"total" | "last24h" | "last7d" | "last30d"

minFacebookLikes?number

Range0 <= value

maxFacebookLikes?number

Range0 <= value

minInstagramFollowers?number

Range0 <= value

maxInstagramFollowers?number

Range0 <= value

minReachPerPage?number

Minimum page reach threshold. Backed by the internal page impressions fields.

Range0 <= value

maxReachPerPage?number

Maximum page reach threshold. Backed by the internal page impressions fields.

Range0 <= value

reachPerPagePeriod?string

Value in"total" | "last24h" | "last7d" | "last30d"

technologies?array<string>

hideLowReach?boolean

Exclude low reach ads. Backed by the internal low impressions flag.

hideNonEuUkAds?boolean

hideSavedAds?boolean

hideDecliningRankAds?boolean

trackedPages?array<string>

maxAdsPerBrand?number

Range0 <= value <= 15

Response Body

`application/json`

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

{
  "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",
        "facebookPageId": "1234567890"
      },
      "content": {
        "title": "Summer Sale",
        "body": "Up to 30% off selected products.",
        "transcript": "Voiceover transcript",
        "landingPageUrl": "https://example.com/products/summer-sale"
      },
      "metrics": {
        "duplicates": 4,
        "reach": 152340
      }
    }
  ],
  "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"
  }
}

{
  "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`