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 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.
"adCopy" | "brand"Enum value accepted by this request. Allowed values: facebook, all. TikTok is not available in public v1.
"facebook" | "all"11 <= value251 <= value <= 100Status filter for this request. Allowed values: active, inactive, all.
"active" | "inactive" | "all"Creative media type filter for this request. Allowed values: image, video, carousel.
"image" | "video" | "carousel"Sort key for this request. Allowed values: relevance, newest, longestRunning, reach.
"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://api.trendtrack.io/v1/ads?search=string"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": [
{
"id": "facebook_123456789",
"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 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.
Response Body
application/json
application/json
application/json
application/json
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",
"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"
]
}
]
}
}
}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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public ad identifier. Currently backed by composite_ad_id.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.trendtrack.io/v1/ads/facebook_123456789"{
"requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
"data": {
"id": "facebook_123456789",
"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 Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.
In: header
Path Parameters
Public ad identifier. Currently backed by composite_ad_id.
Query Parameters
3651 <= value <= 365Response Body
application/json
application/json
application/json
application/json
application/json
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"
]
}
]
}
}
}