Brandtrackers

Get brandtracker scaling ads compatibility data

Legacy compatibility endpoint for clients that still call /scaling-ads. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty.

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

timeWindow'last7d' | 'last14d' | 'last30d' | '7d' | '14d' | '30d'

Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.

sortBy'rankDelta' | 'currentRank' | 'rank_delta' | 'current_rank'

Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.

snapshotDatestring date

Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.

maxCurrentRankinteger

Optional maximum current rank filter. Only ads at or above this current rank are returned.

minRankDeltainteger

Minimum positive rank improvement required for an ad to be returned. Defaults to 1.

Response

Paginated brandtracker scaling 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": {
        "currentRank": 4,
        "previousRank": 17,
        "rankDelta": 13
      },
      "trajectory": [
        {
          "date": "2026-04-20",
          "rank": 4
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  }
}

Changes

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