Ads

List ads

Returns the lightweight public ads collection. This endpoint stays intentionally small and focuses on text search, brand search, simple filters, sorting, and pagination. The search parameter is required; for advanced filtering without a required text search, use POST /v1/ads/query.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

search*string

Canonical text query for the lightweight public ads listing.

searchType?string

Search mode for this request. Allowed values: adCopy, brand.

Value in"adCopy" | "brand"

platform?string

Enum value accepted by this request. Allowed values: facebook, all. TikTok is not available in public v1.

Value in"facebook" | "all"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

status?string

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

Value in"active" | "inactive" | "all"

mediaType?string

Creative media type filter for this request. Allowed values: image, video, carousel. carousel maps to indexed carousel creatives and is not a DCO filter.

Value in"image" | "video" | "carousel"

sortBy?string

Sort key for this request. Allowed values: relevance, newest, longestRunning, reach.

Value in"relevance" | "newest" | "longestRunning" | "reach"

query?stringDeprecated

Deprecated alias for search. Use search instead.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/ads?search=string"

{
  "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": "US",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "isLowReach": false,
        "isMediaChanged": false,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

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.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

search?array<string>

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

searchType?string

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.

Value in"adCopy" | "brand" | "website" | "domain" | "urlContains"

keywordMode?string

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

Value in"any" | "all"

sortBy?string

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

Value in

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

order?string

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

Value in"asc" | "desc"

page?number

Range1 <= value

limit?number

Range1 <= value <= 100

platforms?array<>

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

mediaType?string

Creative media type filter for this request. Allowed values: image, video, carousel. carousel maps to indexed carousel creatives and is not a DCO filter.

Value in"image" | "video" | "carousel"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minFbPageCreationDate?string

Formatdate-time

maxFbPageCreationDate?string

Formatdate-time

minLastSeenDate?string

Formatdate-time

maxLastSeenDate?string

Formatdate-time

minDaysRunning?number

Range0 <= value

maxDaysRunning?number

Range0 <= value

status?string

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

Value in"active" | "inactive" | "all"

minDuplicates?number

Range0 <= value

maxDuplicates?number

Range0 <= value

minDescriptionLength?number

Range0 <= value

maxDescriptionLength?number

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

maxAdOrder?number

Range1 <= value

adRankMode?string

Rank interpretation mode. Allowed values: percentile, rank.

Value in"percentile" | "rank"

adRankBasis?string

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

Value in"current" | "alltime"

maxAdRankValue?number

Range1 <= value

growthRank?

Advanced rank trend filter. Direction filters are ORed; period selects the rank-delta window when every rule uses the same supported window. minChange/unit are accepted for forward compatibility; use minRankDelta for an enforced absolute minimum rank improvement.

rankDeltaWindow?string

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

Value in"7d" | "14d" | "30d"

minRankDelta?number

Minimum absolute rank improvement for ad-rank mover filters.

Range1 <= value

adLanguage?array<string>

cta?array<string>

landingPages?array<string>

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

adCopyHashes?array<string>

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

minReach?number

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

Range0 <= value

maxReach?number

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

Range0 <= value

minAge?number

Range0 <= value

maxAge?number

Range0 <= value

sex?string

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

Value in"men" | "women" | "all"

adCountries?

Countries where the ad is distributed. Uses ISO 3166-1 alpha-2 country codes.

mainCountries?array<string>

spender?string

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

Value in"big-spender" | "rising-star" | "brandtracker"

partners?boolean

partnerIds?array<string>

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

minTraffic?number

Range0 <= value

maxTraffic?number

Range0 <= value

trafficGrowth?

Traffic growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.

minAds?number

Range0 <= value

maxAds?number

Range0 <= value

adsGrowth?

Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.

pageReachGrowth?

Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).

adReachGrowth?

Ad reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).

categoryIds?array<number>

Google category facet ids matched against ads/shop google_categories.

minProducts?number

Range0 <= value

maxProducts?number

Range0 <= value

minBestSellerPrice?number

Range0 <= value

maxBestSellerPrice?number

Range0 <= value

themes?array<string>

pixels?array<string>

excludePixels?array<string>

languages?array<string>

currencies?array<string>

shopifyApps?array<number>

excludeShopifyApps?array<number>

adsTimePeriod?string

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.

Value in"last24h" | "last7d" | "last30d"

minDate?string

Formatdate-time

maxDate?string

Formatdate-time

creationCountry?

Advertiser creation country filter using ISO 3166-1 alpha-2 country codes.

market?

Market filter grouped by primary markets, secondary markets, and excluded markets.

shopifyPlus?string

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

Value in"plus" | "non-plus" | "all"

minTrustpilotScore?number

Minimum Trustpilot score.

Range0 <= value

maxTrustpilotScore?number

Maximum Trustpilot score.

Range0 <= value

minTrustpilotReviews?number

Minimum Trustpilot review count.

Range0 <= value

maxTrustpilotReviews?number

Maximum Trustpilot review count.

Range0 <= value

minSpend?number

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

Range0 <= value

maxSpend?number

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

Range0 <= value

cpm?number

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

Default9

Range0 <= value

spendPeriod?string

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

Value in"total" | "last24h" | "last7d" | "last30d"

reachPeriod?string

Metric period used by minReach/maxReach. Reach is the public Meta Ad Library vocabulary for impressions where available. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

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

Range0 <= value

maxSpendPerPage?number

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

Range0 <= value

spendPerPagePeriod?string

Metric period used by minSpendPerPage/maxSpendPerPage. By itself this parameter does not filter results.

Value in"total" | "last24h" | "last7d" | "last30d"

minFacebookLikes?number

Range0 <= value

maxFacebookLikes?number

Range0 <= value

minInstagramFollowers?number

Range0 <= value

maxInstagramFollowers?number

Range0 <= value

minReachPerPage?number

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

Range0 <= value

maxReachPerPage?number

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

Range0 <= value

reachPerPagePeriod?string

Metric period used by minReachPerPage/maxReachPerPage. Reach is the public Meta Ad Library vocabulary for page impressions where available. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

technologies?array<>

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.

hideLowReach?boolean

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

hideNonEuUkAds?boolean

hideSavedAds?boolean

hideDecliningRankAds?boolean

trackedPages?array<string>

maxAdsPerBrand?number

Range0 <= value <= 15

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/ads/query" \  -H "Content-Type: application/json" \  -d '{    "sortBy": "newest",    "order": "desc",    "status": "active",    "platforms": [      "facebook"    ],    "minDaysRunning": 7,    "reachPeriod": "last7d",    "minReach": 10000,    "limit": 25  }'

{
  "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": "US",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "isLowReach": false,
        "isMediaChanged": false,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Creates or returns the existing TrendTrack public webapp share URL for an ad. This is classified as a workspace-scoped write because it creates share state server-side when needed; delegated OAuth/API-key callers must be workspace writers.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

adId*string

TrendTrack ad identifier returned as adId by the Public API.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/ads/facebook_123456789/share"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "adId": "facebook_123456789",
    "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
    "slug": "example-brand-9a8b7c",
    "shareUrl": "https://app.trendtrack.io/share/ads/example-brand-9a8b7c",
    "sharePath": "/share/ads/example-brand-9a8b7c",
    "createdAt": "2026-04-18T12:30:00.000Z"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get an ad media URL

Returns URL metadata for the best available media asset for an ad. This endpoint does not proxy or download the binary media.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

adId*string

TrendTrack ad identifier returned as adId by the Public API.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/ads/facebook_123456789/media-url"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "adId": "facebook_123456789",
    "mediaType": "video",
    "url": "https://medias.trendtrack.io/ads/ad-1.mp4",
    "urlType": "public_asset",
    "selectedSource": "media_url",
    "mediaUrl": "https://medias.trendtrack.io/ads/ad-1.mp4",
    "thumbnailUrl": "https://medias.trendtrack.io/ads/ad-1-thumb.jpg",
    "filename": "facebook_123456789.mp4"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get an ad by id

Returns a single public ad detail object by ad id. The current backing identifier is the internal composite ad id, but the public contract exposes it as id.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

adId*string

TrendTrack ad identifier returned as adId by the Public API.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/ads/facebook_123456789"

{
  "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": "US",
      "gender": "all",
      "ageMin": 18,
      "ageMax": 65
    },
    "rank": {
      "positionInPage": 3,
      "currentRank": 12,
      "rankDelta": -4,
      "improvementPct": 0.25
    },
    "flags": {
      "isEuAd": true,
      "isLowReach": false,
      "isMediaChanged": false,
      "hasPartnerBadge": true
    },
    "transcript": {
      "language": "en",
      "languageConfidence": 0.97,
      "segments": [
        {
          "start": 0.4,
          "end": 3.2,
          "text": "Save 30% on every order."
        }
      ],
      "fullText": "Save 30% on every order."
    },
    "creativeAnalysis": {
      "hook": {
        "text": "Yes, it is pricey. Also, worth it.",
        "source": "ad_transcripts_hook",
        "sourceDescription": "Existing completed ad transcript hook.",
        "isFallback": false
      }
    },
    "links": {
      "adLibraryUrl": "https://www.facebook.com/ads/library/?view_all_page_id=1234567890&id=9876543210",
      "landingPageUrl": "https://example.com/products/summer-sale"
    },
    "shops": [
      {
        "shopId": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
        "domain": "example.com",
        "name": "Example Shop",
        "isPrimary": true,
        "traffic": 45231,
        "categories": [
          "Fashion",
          "Accessories"
        ]
      }
    ],
    "pageAnalytics": {
      "impressionsHistory": [
        {
          "date": "2026-04-18",
          "totalImpressions": 12340
        }
      ],
      "facebookLikesHistory": [
        {
          "date": "2026-04-18",
          "value": 84000
        }
      ],
      "instagramFollowersHistory": [
        {
          "date": "2026-04-18",
          "value": 84000
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get ad reach history

Returns the public daily reach history for one ad. The series is intentionally lightweight and keeps reach as the canonical metric term.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

adId*string

TrendTrack ad identifier returned as adId by the Public API.

Query Parameters

limit?integer

Default365

Range1 <= value <= 365

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/ads/facebook_123456789/reach-history"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "date": "2026-04-18",
      "reach": 152340
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`