Brandtrackers

Get current ranked top ads

Canonical current-ranking endpoint for a brandtracker. Use sortBy=currentRank for the current Facebook page rank, sortBy=reach/reachDelta1d/reachDelta7d/reachDelta30d for reach rankings, and sortBy=rankDelta7d/rankDelta14d/rankDelta30d for rank movers. period and snapshotDate are deprecated compatibility parameters and are ignored on this current-ranking path.

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

Path parameters

brandtrackerIdstring required

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query parameters

pageinteger

Pagination page number. Defaults to 1.

limitinteger

Maximum number of items to return. Defaults to 20.

facebookPageIdstring

Optional Facebook page id belonging to this brandtracker. When omitted, the primary Facebook page is used.

allFacebookPagesboolean

When true, aggregate all selected Facebook pages. Current ranks are page-local, so ties across pages are expected. Cannot be combined with facebookPageId.

euOnlyboolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

sortBy'currentRank' | 'rankDelta' | 'rankDelta7d' | 'rankDelta14d' | 'rankDelta30d' | 'reach' | 'reachDelta1d' | 'reachDelta7d' | 'reachDelta30d' | 'daysRunning' | 'duplicates'

Sort key for canonical current rankings. Use currentRank for the selected Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings.

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

Preferred activity filter. active returns active ads, inactive returns inactive ads, all returns both. When supplied, it takes precedence over includeInactive.

includeInactiveboolean

Deprecated. When status is omitted, includeInactive=true maps to status=all; ignored when status is supplied.

period'today' | 'yesterday' | 'last1d' | 'last7d' | 'last14d' | 'last30d' | 'total'

Optional rolling top-ads period. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.

string date
OR
'latest'
Example:2026-04-20

Deprecated compatibility parameter accepted but ignored by canonical top-ads current ranking. Use freshness/system endpoints for snapshot availability checks.

Response

Paginated brandtracker top 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": [
    {
      "ad": {
        "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
        }
      },
      "metrics": {
        "totalReach": 152340,
        "duplicateCount": 4,
        "daysRunning": 27,
        "currentRank": 3
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

Changes

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