Trendtrack
Trendtrack
DashboardGet API keyIntroducción
Referencia de la API
Ads
List adsQuery adsGet an ad by idGet ad reach history
Advertisers
Brandtrackers
Discovery
Emails
Facets
Favorites
Identity
Shops
System
Usage
Workspace
ReferenciaAPI

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.

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

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
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.

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
AuthorizationBearer <token>

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

In: header

Path Parameters

adId*string

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
AuthorizationBearer <token>

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

In: header

Path Parameters

adId*string

Public ad identifier. Currently backed by composite_ad_id.

Query Parameters

limit?integer
Default365
Range1 <= value <= 365

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/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"
          ]
        }
      ]
    }
  }
}

Referencia de la API

Explora la referencia agrupada de endpoints para shops, advertisers, ads, favorites, usage y workspace.

List ads

Next Page

search?array<string>

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

searchType?string

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

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" | "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.

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. Currently backed by the 3-day rank direction field; all provided directions are ORed while grouping, period, minChange, and unit are accepted for forward compatibility.

adLanguage?array<string>
cta?array<string>
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
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>

Category IDs for the ads query surface.

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: 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