Brandtrackers

List brandtracker partnership ads

Returns deduped Meta partnership ad groups for one active workspace brandtracker. This endpoint always filters to ads with a partner badge and reuses the public ad summary shape.

get/v1/brandtrackers/{brandtrackerId}/partnership-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}/partnership-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.

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.

partnerIdstring

Single partner identifier alias. It is merged with partnerIds when both are provided.

Response

Paginated brandtracker partnership 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.