Ads

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. Search terms are optional in this route.

post/v1/ads/query

Request

  • Base URL: https://api.trendtrack.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.trendtrack.io/v1/ads/query
  • Auth: HTTP bearer

Request body

searchstring[]

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

searchType'adCopy' | 'brand' | 'website' | 'domain' | 'urlContains'

Search mode for this request. Public camelCase values map to the same internal /ads fields: adCopy → ad_copy, brand → brand, website → website_copy, domain → domain, urlContains → url_contains.

keywordMode'any' | 'all'

How multiple search keywords are combined. Allowed values: any, all.

sortBy'createdAt' | 'longestRunning' | 'relevance' | 'relevanceScore' | 'newest' | 'mostDuplicates' | 'reach' | 'reachDelta1d' | 'reachDelta7d' | 'reachDelta30d' | 'rankDelta7d' | 'rankDelta14d' | 'rankDelta30d' | 'adOrder'

Sort key for this request. Allowed values: createdAt, longestRunning, relevance, relevanceScore, newest, mostDuplicates, reach, reachDelta1d, reachDelta7d, reachDelta30d, adOrder.

order'asc' | 'desc'

Sort direction for this request. Allowed values: asc, desc.

pagenumber
limitnumber
platformsPublicApiAdsQueryPlatform[]

Accepted public v1 platform values. TikTok is not available in public v1.

mediaType'image' | 'video' | 'carousel'
createdAfterstring date-time
createdBeforestring date-time
minFbPageCreationDatestring date-time
maxFbPageCreationDatestring date-time
minLastSeenDatestring date-time
maxLastSeenDatestring date-time
minDaysRunningnumber
maxDaysRunningnumber
status'active' | 'inactive' | 'all'
minDuplicatesnumber
maxDuplicatesnumber
minDescriptionLengthnumber
maxDescriptionLengthnumber
minVideoDurationnumber
maxVideoDurationnumber
maxAdOrdernumber
adRankMode'percentile' | 'rank'

Rank interpretation mode. Allowed values: percentile, rank.

adRankBasis'current' | 'alltime'

Rank basis used for ad rank filters. Allowed values: current, alltime.

maxAdRankValuenumber
rankDeltaWindow'7d' | '14d' | '30d'

Rank-delta window used by growthRank/minRankDelta. Overrides the window inferred from growthRank.period.

minRankDeltanumber

Minimum absolute rank improvement for ad-rank mover filters.

adLanguagestring[]
ctastring[]
landingPagesstring[]

Landing page URL/domain filters. Mirrors the app ads table landingPages filter.

adCopyHashesstring[]

Ad copy hash filters. Mirrors the app ads table adCopyHashes filter.

minReachnumber

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

maxReachnumber

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

minAgenumber
maxAgenumber
sex'men' | 'women' | 'all'

Audience gender filter. Allowed values: men, women, all.

mainCountriesstring[]

Primary audience country filter, backed by Meta's EU/UK ad transparency reporting. Only EU/EEA, UK and French overseas codes exist in that data: US and other non-EU codes match nothing. Use adCountries for those markets.

spender'big-spender' | 'rising-star' | 'brandtracker'

Spender segment filter. Allowed values: big-spender, rising-star, brandtracker.

partnersboolean
partnerIdsstring[]

Partner badge ids to include. Mirrors the app ads table partnerIds filter.

minTrafficnumber
maxTrafficnumber
minAdsnumber
maxAdsnumber
categoryIdsnumber[]

Google category facet ids matched against ads/shop google_categories.

minProductsnumber
maxProductsnumber
minBestSellerPricenumber
maxBestSellerPricenumber
themesstring[]
pixelsstring[]
excludePixelsstring[]
languagesstring[]
currenciesstring[]
shopifyAppsstring[]

Shopify app UUIDs returned by the Shopify Apps facets endpoint.

excludeShopifyAppsstring[]

Shopify app UUIDs to exclude. Values must not overlap shopifyApps.

adsTimePeriod'last24h' | 'last7d' | 'last30d'

Relative ad first-seen time window. When createdAfter is omitted, this is converted to an internal first-seen lower bound at the UTC day boundary for the selected period. It also selects the ads metric period used by minAds/maxAds.

minDatestring date-time
maxDatestring date-time
shopifyPlus'plus' | 'non-plus' | 'all'

Shopify Plus filter. Allowed values: plus, non-plus, all.

minTrustpilotScorenumber

Minimum Trustpilot score.

maxTrustpilotScorenumber

Maximum Trustpilot score.

minTrustpilotReviewsnumber

Minimum Trustpilot review count.

maxTrustpilotReviewsnumber

Maximum Trustpilot review count.

minSpendnumber

Minimum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9.

maxSpendnumber

Maximum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9.

cpmnumber

CPM in euros per 1,000 reach used for spend filters and estimatedSpend. Defaults to 9 when omitted.

spendPeriod'total' | 'last24h' | 'last7d' | 'last30d'

Metric period used by minSpend/maxSpend. By itself this parameter does not filter results.

reachPeriod'total' | 'last24h' | 'last7d' | 'last30d'

Metric period used by minSpend/maxSpend. By itself this parameter does not filter results.

minSpendPerPagenumber

Minimum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9.

maxSpendPerPagenumber

Maximum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9.

spendPerPagePeriod'total' | 'last24h' | 'last7d' | 'last30d'

Metric period used by minSpend/maxSpend. By itself this parameter does not filter results.

minFacebookLikesnumber
maxFacebookLikesnumber
minInstagramFollowersnumber
maxInstagramFollowersnumber
minReachPerPagenumber

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

maxReachPerPagenumber

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

reachPerPagePeriod'total' | 'last24h' | 'last7d' | 'last30d'

Metric period used by minSpend/maxSpend. By itself this parameter does not filter results.

technologiesstring[]

Technology slugs supported by the current ads index. Supported values: checkoutchamp, clickfunnels, funnelish, gempages, magento, odoo, pagefly, prestashop, shopify, shoplazza, shopline, squarespace, wheelio, wix, woocommerce, wordpress, zipify-pages.

hideLowReachboolean

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

hideNonEuUkAdsboolean
hideSavedAdsboolean
hideDecliningRankAdsboolean
trackedPagesstring[]
maxAdsPerBrandnumber

Example request

{
  "search": [
    "summer dress",
    "linen"
  ],
  "page": 1,
  "limit": 50,
  "platforms": [
    "facebook"
  ],
  "growthRank": {
    "anyOf": [
      {
        "all": [
          {
            "minChange": 20
          }
        ]
      }
    ]
  },
  "adCountries": {
    "include": [
      "US",
      "CA"
    ],
    "exclude": [
      "BR",
      "IN"
    ]
  },
  "trafficGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "value": 50
          }
        ]
      }
    ]
  },
  "adsGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "value": 50
          }
        ]
      }
    ]
  },
  "pageReachGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "value": 50
          }
        ]
      }
    ]
  },
  "adReachGrowth": {
    "anyOf": [
      {
        "all": [
          {
            "value": 50
          }
        ]
      }
    ]
  },
  "shopifyApps": [
    "41c143a7-0000-4000-8000-000000000000"
  ],
  "excludeShopifyApps": [
    "52d254b8-0000-4000-8000-000000000000"
  ],
  "creationCountry": {
    "include": [
      "US",
      "CA"
    ],
    "exclude": [
      "BR",
      "IN"
    ]
  },
  "market": {
    "main": [
      "US"
    ],
    "among": [
      "CA",
      "GB"
    ],
    "exclude": [
      "AU"
    ]
  },
  "technologies": [
    "shopify"
  ]
}

Response

Paginated advanced ads query response using the public ads contract. The response also includes the X-Request-Id header.

requestIdstring required

Request identifier mirrored in the X-Request-Id response header.

Example response

{
  "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,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.