GET /v1/brands/search

Find a brand by name or shop domain

Find a competitor by name or shop domain, before get_brand or brand_changes. Use it whenever the user names a brand or store ('show me Epycure's ads', 'what is Leaf running', 'gymshark.com'). Fuzzy: returns up to 10 confirmed e-commerce brands, best first, each with what matched (page name or shop domain), its page_id, shop link, and how many ads, winners and active ads Poseidon holds. No search of people's names: a page named after a person is found by its shop domain only. Free.

Cost: Free.

Parameters

Parameter	Type	What it does
`q` required	string

Errors

`400`	A parameter is refused (the answer lists the accepted values). Not billed.
`401`	Missing, unknown or revoked API key.
`429`	Too many requests for this key. Wait Retry-After seconds. Not billed.
`503`	Server busy or a query took too long. Retry. Not billed.

Request

curl -s "https://api.askposeidon.app/v1/brands/search?q=epycure" \
  -H "Authorization: Bearer $POSEIDON_API_KEY"

Response

{
  "data": {
    "query": "epycure",
    "brands": [
      {
        "page_id": "2218331548432159",
        "name": "Epycure",
        "shop_domain": "epycure.com",
        "shop_url": "https://epycure.com",
        "matched_on": "shop domain",
        "matched_text": "epycure.com",
        "match_score": 1.0,
        "ads_in_poseidon": 30,
        "winners_21_days": 28,
        "active_ads": 28,
        "library_url": "https://www.facebook.com/ads/library/?view_all_page_id=2218331548432159"
      }
    ],
    "note": "Confirmed e-commerce brands only. Then call get_brand with a page_id for its winners, scripts and A/B tests, or brand_changes for what changed since a date."
  },
  "meta": {
    "endpoint": "find_brand",
    "api_version": "1.22.2",
    "credits_charged": 0,
    "credits_left": 1120,
    "answered_at": "2026-11-13T14:59:52+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."
  }
}