GET /v1/filters
What you can filter on, with live counts
Free. What Poseidon can filter on, with live counts: niches, Meta display formats, countries with reach data, age ranges, hook types (none measured yet), sort orders, the winner rule and the coverage note. Call it first.
Cost: Free.
Parameters
No parameters.
Errors 401Missing, unknown or revoked API key. 429Too many requests for this key. Wait Retry-After seconds. Not billed. 503Server busy or a query took too long. Retry. Not billed.
Request
curl -s "https://api.askposeidon.app/v1/filters" \
-H "Authorization: Bearer $POSEIDON_API_KEY"Response
{
"data": {
"niche": {
"values": [
{
"v": "weight loss",
"brands": 440,
"ads": 12408
},
{
"v": "cellulite",
"brands": 174,
"ads": 4823
}
],
"note": "niche = the niche of the keyword search that found the brand on the Ad Library. It is a fact about our search, not a judgment of the brand: a brand found by 'weight loss' may sell something else."
},
"format": {
"values": [
{
"v": "VIDEO",
"ads": 16919
},
{
"v": "IMAGE",
"ads": 12457
}
],
"note": "Meta's display format as shown on the Ad Library. Creative types such as UGC, VSL or podcast are not labelled on any ad yet, so they cannot be filtered."
},
"country": {
"values": [
{
"v": "BE",
"ads_with_reach": 939
},
{
"v": "FR",
"ads_with_reach": 883
}
],
"note": "An ad is in a country when Meta's reach breakdown shows people reached there. Ads whose reach was never read have no country."
},
"age": {
"values": [
"13-17",
"18-24"
]
},
"gender": {
"values": [
"female",
"male"
]
},
"hook_type": {
"values": [],
"note": "Hook types are not measured on any ad yet: this filter returns nothing."
},
"sort": {
"values": [
"country_share",
"days_live"
]
},
"reach_reads": {
"first": "2026-11-11",
"last": "2026-11-12",
"ads": 3661
},
"winner_rule": "A winner is an ad live for at least 21 days: days between Meta's start date and its stop date, or our last read if it is still active. Override with min_days_live.",
"coverage": "Ads delivered in the EU or UK only. The only number of people shown is Meta's EU total reach (eu_reach, \"EU reach (Meta's total)\"), as read on the date shown. Meta publishes no spend or impressions for commercial ads. Countries, ages and genders are shown only as shares of Meta's age x gender breakdown of the same read, never as numbers of people: Meta's breakdown rows do not add up to its EU total (measured 0.93x to 1.10x on 3,820 reads), so a country figure in people would not be a fact."
},
"meta": {
"endpoint": "filters",
"api_version": "1.1.0",
"credits_charged": 0,
"credits_left": 500,
"answered_at": "2026-11-12T22:11:37+00:00",
"coverage": "Ads delivered in the EU or UK only. The only number of people shown is Meta's EU total reach (eu_reach, \"EU reach (Meta's total)\"), as read on the date shown. Meta publishes no spend or impressions for commercial ads. Countries, ages and genders are shown only as shares of Meta's age x gender breakdown of the same read, never as numbers of people: Meta's breakdown rows do not add up to its EU total (measured 0.93x to 1.10x on 3,820 reads), so a country figure in people would not be a fact."
}
}