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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Query Parameters
Canonical text query for the lightweight public ads listing.
Search mode for this request. Allowed values: adCopy, brand.
Enum value accepted by this request. Allowed values: facebook, all. TikTok is not available in public v1.
Status filter for this request. Allowed values: active, inactive, all.
Creative media type filter for this request. Allowed values: image, video, carousel. carousel maps to indexed carousel creatives and is not a DCO filter.
Sort key for this request. Allowed values: relevance, newest, longestRunning, reach.
Deprecated alias for search. Use search instead.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/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": "FR", "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" ] } ] } }}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 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.
Optional list of search terms used by the advanced ads query engine.
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.
How multiple search keywords are combined. Allowed values: any, all.
Sort key for this request. Allowed values: createdAt, longestRunning, relevance, relevanceScore, newest, mostDuplicates, reach, reachDelta1d, reachDelta7d, reachDelta30d, adOrder.
Sort direction for this request. Allowed values: asc, desc.
Accepted public v1 platform values. TikTok is not available in public v1.
Creative media type filter for this request. Allowed values: image, video, carousel. carousel maps to indexed carousel creatives and is not a DCO filter.
Status filter for this request. Allowed values: active, inactive, all.
Rank interpretation mode. Allowed values: percentile, rank.
Rank basis used for ad rank filters. Allowed values: current, alltime.
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.
Rank-delta window used by growthRank/minRankDelta. Overrides the window inferred from growthRank.period.
Minimum absolute rank improvement for ad-rank mover filters.
Landing page URL/domain filters. Mirrors the app ads table landingPages filter.
Ad copy hash filters. Mirrors the app ads table adCopyHashes filter.
Minimum reach threshold. Backed by the internal reach/impressions analytics fields.
Maximum reach threshold. Backed by the internal reach/impressions analytics fields.
Audience gender filter. Allowed values: men, women, all.
Countries where the ad is distributed. Uses ISO 3166-1 alpha-2 country codes.
Primary audience country filter, backed by Meta's EU/UK ad transparency reporting. Only EU/EEA, UK and French overseas codes exist in that data: US and other non-EU codes match nothing. Use adCountries for those markets.
Spender segment filter. Allowed values: big-spender, rising-star, brandtracker.
Partner badge ids to include. Mirrors the app ads table partnerIds filter.
Traffic growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.
Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all). Values are percentage thresholds.
Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).
Ad reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all).
Google category facet ids matched against ads/shop google_categories.
Shopify app UUIDs returned by the Shopify Apps facets endpoint.
Shopify app UUIDs to exclude. Values must not overlap shopifyApps.
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.
Advertiser creation country filter using ISO 3166-1 alpha-2 country codes.
Market filter grouped by primary markets, secondary markets, and excluded markets.
Shopify Plus filter. Allowed values: plus, non-plus, all.
Minimum Trustpilot score.
Maximum Trustpilot score.
Minimum Trustpilot review count.
Maximum Trustpilot review count.
Minimum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9.
Maximum estimated spend. Uses cpm when provided, otherwise the public API default CPM of 9.
CPM in euros per 1,000 reach used for spend filters and estimatedSpend. Defaults to 9 when omitted.
Metric period used by minSpend/maxSpend. By itself this parameter does not filter results.
Metric period used by minReach/maxReach. Reach is the public Meta Ad Library vocabulary for impressions where available. Allowed values: total, last24h, last7d, last30d.
Minimum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9.
Maximum estimated spend per page. Uses cpm when provided, otherwise the public API default CPM of 9.
Metric period used by minSpendPerPage/maxSpendPerPage. By itself this parameter does not filter results.
Minimum page reach threshold. Backed by the internal page impressions fields.
Maximum page reach threshold. Backed by the internal page impressions fields.
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.
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.
Exclude low reach ads. Backed by the internal low impressions flag.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/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": "FR", "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" ] } ] } }}Aggregates distinct normalized landing-page URLs for Meta pages or one shop domain. Charges one credit per distinct URL returned and never returns ad rows.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Query Parameters
Repeated or comma-separated Meta/Facebook page identifiers. Mutually exclusive with scopeDomain.
Shop URL or hostname. Mutually exclusive with scopeTrackedPages.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/ads/facets/landing-pages"{ "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "data": [ { "url": "https://www.example.com/products/item", "usageCount": 8, "activeAdsCount": 3 } ], "meta": { "scopeType": "trackedPages", "scopeValueCount": 2, "status": "all", "limit": 100, "isTruncated": false }}{ "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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Trendtrack ad identifier returned as adId by the Public API.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/ads/facebook_123456789/share"{ "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc", "data": { "adId": "facebook_123456789", "id": "share_3f8aa146-6f96-46e8-9781-64db5166f9a8", "slug": "string", "shareUrl": "https://app.trendtrack.io/en/share/ad/q8Xr2mVb0aT4yKpZ7nWc1eLs9dHf3uJg6oBi5RtY0xA", "sharePath": "/en/share/ad/q8Xr2mVb0aT4yKpZ7nWc1eLs9dHf3uJg6oBi5RtY0xA", "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" ] } ] } }}Revokes the public share link of this ad for its author — the delegated user, otherwise the workspace owner — including the link that author shared from the Trendtrack app: it is the same link, reused. Also deletes that author's legacy share of the ad, so its old /share/ads/ URL stops resolving. deleted is true when anything was revoked or deleted.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/ads/facebook_123456789/share"{ "requestId": "string", "data": { "adId": "facebook_123456789", "deleted": true }}{ "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" ] } ] } }}Returns URL metadata for the best available media asset for an ad. This endpoint does not proxy or download the binary media.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Trendtrack ad identifier returned as adId by the Public API.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/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" ] } ] } }}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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Trendtrack ad identifier returned as adId by the Public API.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/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": "FR", "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 } ] }, "resolvedFrom": { "requestedId": "facebook_2938968053111742", "reason": "duplicate_group" } }}{ "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" ] } ] } }}Returns the public daily reach history for one ad. The series is intentionally lightweight and keeps reach as the canonical metric term.
Authorization
publicApiBearer Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Trendtrack ad identifier returned as adId by the Public API.
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/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" ] } ] } }}