Brandtrackers

List brandtracker ads

Returns the Meta ads for one active workspace brandtracker resolved from brandtracker.id to fb_page_id. The response reuses the public ad summary shape.

get/v1/brandtrackers/{brandtrackerId}/ads

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/brandtrackers/{brandtrackerId}/ads
Auth: HTTP bearer

Path parameters

brandtrackerIdstring required

Example:1e08fa85-625a-4ba5-b673-d2a4b7bc7c55

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Query parameters

pageinteger

limitinteger

Sort key. The adOrder value also accepts ad_order and ad-order aliases.

status'all' | 'active' | 'inactive'

Status filter for this request. Allowed values: all, active, inactive.

mediaType'all' | 'image' | 'video'

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

keywordsstring[]

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode'any' | 'all'

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

createdAfterstring date-time

createdBeforestring date-time

minDaysRunninginteger

maxDaysRunninginteger

minDuplicatesinteger

maxDuplicatesinteger

landingPagesstring[]

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguagestring[]

Ad languages. Repeated query params and comma-separated values are both accepted.

ctastring[]

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashesstring[]

12-character MD5 prefixes for ad copy descriptions.

adCountriesstring

Example:US=include,FR=exclude

Comma-separated country include/exclude filters.

mainCountriesstring[]

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnlyboolean

When true, keep only ads flagged as EU ads.

partnersboolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIdsstring[]

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReachinteger

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

maxReachinteger

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

cpmnumber

CPM used to convert spend filters into reach thresholds.

minSpendnumber

maxSpendnumber

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

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

minSpendPerPagenumber

maxSpendPerPagenumber

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

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

hideLowReachboolean

When true, hides ads flagged as low reach.

minAgeinteger

maxAgeinteger

sex'men' | 'women' | 'all'

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

minFacebookLikesinteger

maxFacebookLikesinteger

minInstagramFollowersinteger

maxInstagramFollowersinteger

minVideoDurationnumber

maxVideoDurationnumber

minDescriptionLengthinteger

maxDescriptionLengthinteger

linkedDomainstring

Example:example.com

Linked domain filter. URLs are normalized to their hostname before validation.

growthRankPublicApiBrandtrackerAdsGrowthRank[]

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDatestring date

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Response

Paginated brandtracker ads response. 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.