Trendtrack
Trendtrack
DashboardGet API keyIntroduction
Référence API
Ads
Advertisers
List advertisersQuery advertisersList ads for an advertiserGet advertiser detail
Brandtrackers
Discovery
Emails
Facets
Favorites
Identity
Shops
System
Usage
Workspace
RéférenceAPI

Advertisers

List advertisers

Returns the lightweight public advertisers collection. This endpoint stays intentionally simple and focuses on brand/domain search, pagination, ordering, and stable scalar filters. Use POST /v1/advertisers/query for the advanced discovery surface.

Authorization

publicApiBearer
AuthorizationBearer <token>

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

In: header

Query Parameters

search?array<string>

Optional advertiser search keywords. Repeated query params and comma-separated values are both accepted.

searchType?string

Simple search strategy for the advertisers collection. Use POST /v1/advertisers/query for advanced text resolution modes.

Value in"brand" | "domain"
keywordMode?string

How multiple search keywords should combine. Defaults to any.

Value in"any" | "all"
sortBy?string

Primary sort key for advertiser discovery. Defaults to relevance.

Value in"relevance" | "newest" | "activeAds" | "newAds" | "euAdsShare" | "reach" | "reach14d" | "followers"
order?string

Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.

Value in"asc" | "desc"
offset?integer

Pagination offset. Defaults to 0.

Default0
Range0 <= value
limit?integer

Maximum number of advertisers to return. Defaults to 20.

Default20
Range1 <= value <= 100
minFbPageCreationDate?string

Inclusive lower bound for the Facebook page creation date filter.

Formatdate
maxFbPageCreationDate?string

Inclusive upper bound for the Facebook page creation date filter.

Formatdate
minActiveAds?integer
Range0 <= value
maxActiveAds?integer
Range0 <= value
adsTimePeriod?string

Enum value accepted by this request. Allowed values: current, last24h, last7d, last14d, last30d.

Value in"current" | "last24h" | "last7d" | "last14d" | "last30d"
minFacebookLikes?integer
Range0 <= value
maxFacebookLikes?integer
Range0 <= value
minInstagramFollowers?integer
Range0 <= value
maxInstagramFollowers?integer
Range0 <= value
minAdsLaunched?integer
Range0 <= value
maxAdsLaunched?integer
Range0 <= value
adsLaunchedPeriod?string

Time window accepted by this request. Allowed values: last24h, last7d, last14d, last30d, last90d.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d"
minReach?integer

Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

Range0 <= value
maxReach?integer

Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

Range0 <= value
reachPeriod?string

Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: last24h, last7d, last14d, last30d, last90d, total.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d" | "total"
pageType?array<>

Enum value accepted by this request. Allowed values: influencer, brand.

categoryIds?array<>

Simple advertiser category filter. Repeated query params and comma-separated values are both accepted. Equivalent to POST /v1/advertisers/query pageNiches.among.

shopifyLinked?string

Filter by indexed linked-site Shopify technology. no means no indexed Shopify technology is present for the advertiser.

Value in"yes" | "no" | "all"
gender?string

Enum value accepted by this request. Allowed values: male, female, all.

Value in"male" | "female" | "all"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.trendtrack.io/v1/advertisers"
{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "61554990830184",
      "platform": "facebook",
      "facebookPageId": "61554990830184",
      "name": "Example Brand",
      "logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "profile": {
        "likes": 125000,
        "instagramFollowers": 89000,
        "createdAt": "2019-01-04T00:00:00.000Z"
      },
      "advertising": {
        "activeAds": 12,
        "reach30d": 452000
      },
      "lastAds": [
        {
          "id": "facebook:123456789",
          "mediaUrl": "https://medias.trendtrack.io/facebook/media/ad-1.mp4",
          "thumbnailUrl": "https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"
        }
      ],
      "mainLandingPages": [
        {
          "landingPage": "https://example.com/products/summer",
          "screenshotUrl": "https://medias.trendtrack.io/landing-pages/summer.jpg"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 128
  },
  "meta": {
    "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"
          ]
        }
      ]
    }
  }
}

Query advertisers

Returns the advanced public advertisers query surface. This endpoint supports the current richer advertiser discovery filters through a structured public camelCase contract while keeping the response aligned with the standard public advertiser summary shape. categoryIds is a shorthand for pageNiches.among; send categoryIds or pageNiches (not both). Empty JSON bodies are valid and use defaults.

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/advertisers/query" \  -H "Content-Type: application/json" \  -d '{    "search": [      "athleisure"    ],    "searchType": "brand",    "sortBy": "reach",    "order": "desc",    "adsTimePeriod": "last7d",    "minActiveAds": 10,    "reachPeriod": "last14d",    "minReach": 50000,    "categoryIds": [      254    ],    "pageType": [      "brand"    ],    "limit": 20,    "offset": 0  }'
{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "61554990830184",
      "platform": "facebook",
      "facebookPageId": "61554990830184",
      "name": "Example Brand",
      "logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "profile": {
        "likes": 125000,
        "instagramFollowers": 89000,
        "createdAt": "2019-01-04T00:00:00.000Z"
      },
      "advertising": {
        "activeAds": 12,
        "reach30d": 452000
      },
      "lastAds": [
        {
          "id": "facebook:123456789",
          "mediaUrl": "https://medias.trendtrack.io/facebook/media/ad-1.mp4",
          "thumbnailUrl": "https://medias.trendtrack.io/facebook/thumb/ad-1.jpg"
        }
      ],
      "mainLandingPages": [
        {
          "landingPage": "https://example.com/products/summer",
          "screenshotUrl": "https://medias.trendtrack.io/landing-pages/summer.jpg"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 128
  },
  "meta": {
    "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"
          ]
        }
      ]
    }
  }
}

List ads for an advertiser

Returns a paginated list of ads for the requested page-centric advertiser. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.

Authorization

publicApiBearer
AuthorizationBearer <token>

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

In: header

Path Parameters

advertiserId*string

Public advertiser identifier. Current MVP uses the Facebook page id directly.

Query Parameters

limit?integer
Default25
Range1 <= value <= 100
offset?integer
Default0
Range0 <= value
status?string

Filter ads by activity status. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"
mediaType?string

Filter ads by creative media type. Allowed values: all, image, video.

Value in"all" | "image" | "video"
sortBy?string

Sort key for advertiser ads. reach uses the public reach/impressions metric; no impressions alias is accepted on this endpoint.

Value in"newest" | "createdAt" | "longestRunning" | "reach" | "duplicates"
order?string

Sort direction. Allowed values: asc, desc.

Value in"asc" | "desc"
cpm?integer

Optional CPM override used to compute estimated spend in the ads response.

Default9
Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.trendtrack.io/v1/advertisers/61554990830184/ads"
{
  "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": {
    "limit": 25,
    "offset": 0,
    "total": 128
  }
}
{
  "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 advertiser detail

Returns the page-centric advertiser detail. In this first MVP iteration, advertiserId resolves directly from the Facebook page id.

Authorization

publicApiBearer
AuthorizationBearer <token>

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

In: header

Path Parameters

advertiserId*string

Public advertiser identifier. Current MVP uses the Facebook page id directly.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.trendtrack.io/v1/advertisers/61554990830184"
{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "61554990830184",
    "platform": "facebook",
    "facebookPageId": "61554990830184",
    "name": "Example Brand",
    "logoUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
    "profile": {
      "likes": 125000,
      "instagramFollowers": 89000,
      "createdAt": "2019-01-04T00:00:00.000Z"
    },
    "linkedShops": [
      {
        "shopId": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
        "domain": "example.com",
        "name": "Example Shop",
        "isPrimary": true
      }
    ],
    "advertising": {
      "activeAds": 12,
      "reach30d": 452000,
      "countryDistribution": [
        {
          "countryCode": "US",
          "share": 0.42
        }
      ]
    },
    "lastAds": [
      {
        "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
        }
      }
    ]
  }
}
{
  "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

Previous Page

List advertisers

Next Page

search?array<string>
searchType?string

Advanced search strategy for advertiser discovery. Supports content and URL resolution modes in addition to simple brand/domain search.

Value in"brand" | "domain" | "adCopy" | "websiteCopy" | "urlContains"
keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"
sortBy?string

Sort key for this request. Allowed values: relevance, newest, activeAds, newAds, euAdsShare, reach, reach14d, followers.

Value in"relevance" | "newest" | "activeAds" | "newAds" | "euAdsShare" | "reach" | "reach14d" | "followers"
order?string

Sort order. Ignored when sortBy=relevance because relevance is always ranked descending.

Value in"asc" | "desc"
offset?number
Range0 <= value
limit?number
Range1 <= value <= 100
minFbPageCreationDate?string
maxFbPageCreationDate?string
minActiveAds?number
Range0 <= value
maxActiveAds?number
Range0 <= value
adsTimePeriod?string

Enum value accepted by this request. Allowed values: current, last24h, last7d, last14d, last30d.

Value in"current" | "last24h" | "last7d" | "last14d" | "last30d"
minFacebookLikes?number
Range0 <= value
maxFacebookLikes?number
Range0 <= value
minInstagramFollowers?number
Range0 <= value
maxInstagramFollowers?number
Range0 <= value
minAdsLaunched?number
Range0 <= value
maxAdsLaunched?number
Range0 <= value
adsLaunchedPeriod?string

Time window accepted by this request. Allowed values: last24h, last7d, last14d, last30d, last90d.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d"
minReach?number

Minimum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

Range0 <= value
maxReach?number

Maximum advertiser reach threshold. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available.

Range0 <= value
reachPeriod?string

Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: last24h, last7d, last14d, last30d, last90d, total.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d" | "total"
minSpendPerPage?number

Minimum estimated spend per page. Converted internally through CPM and reach/impressions fields. If cpm is omitted or zero, the API uses a default CPM of 9.

Range0 <= value
maxSpendPerPage?number

Maximum estimated spend per page. Converted internally through CPM and reach/impressions fields. If cpm is omitted or zero, the API uses a default CPM of 9.

Range0 <= value
spendPerPagePeriod?string

Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: last24h, last7d, last14d, last30d, last90d, total.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d" | "total"
cpm?number

CPM used to convert spend filters into reach/impressions-based ES ranges. Spend-per-page filters default to CPM 9 when this value is omitted or zero.

Range0 <= value
minReachPerPage?number

Minimum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

Range0 <= value
maxReachPerPage?number

Maximum reach-per-page filter. Reach corresponds to the public impressions-style metric from Meta Ad Library data.

Range0 <= value
reachPerPagePeriod?string

Reach/impressions metric window. In Meta Ad Library vocabulary, reach is the public-facing impressions-style metric where available. Allowed values: last24h, last7d, last14d, last30d, last90d, total.

Value in"last24h" | "last7d" | "last14d" | "last30d" | "last90d" | "total"
adLanguage?array<string>
technologies?array<string>
adCountries?

Countries where the advertiser is distributing ads. Uses ISO 3166-1 alpha-2 country codes.

mainCountries?array<string>

Primary countries to match.

countryFilterMode?string

Enum value accepted by this request. Allowed values: reach, adCount.

Value in"reach" | "adCount"
adsGrowth?

Ads growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.

pageReachGrowth?

Page reach growth filter. Uses OR groups (anyOf) made of AND-ed rules (all), with rule fields period, operator, and value.

ageRanges?array<string>
pageType?array<>

Enum value accepted by this request. Allowed values: influencer, brand.

categoryIds?array<number>

Simple advertiser category filter. Equivalent to pageNiches.among. Use pageNiches when you need main or exclude matching.

pageNiches?

Advanced advertiser page category filter. Use main to require the primary page niche, among to match any page niche, and exclude to remove categories. categoryIds is a shorthand for pageNiches.among.

minPartnershipPercentage?number
Range0 <= value <= 100
shopifyLinked?string

Filter by indexed linked-site Shopify technology. no means no indexed Shopify technology is present for the advertiser.

Value in"yes" | "no" | "all"
gender?string

Enum value accepted by this request. Allowed values: male, female, all.

Value in"male" | "female" | "all"