POST /v1/watchlist

Add or remove watched brands

Save competitors to watch, on your key: add or remove brands by page_id (get it with find_brand), up to 25. Use it when the user says 'watch these brands', 'add X to my competitors', 'stop watching Y'. Only confirmed e-commerce brands can be added. Returns the watchlist. Free.

Cost: Free.

Parameters

No parameters.

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 -X POST "https://api.askposeidon.app/v1/watchlist" \
  -H "Authorization: Bearer $POSEIDON_API_KEY" \
  -H "Content-Type: application/json" \
  -d 'null'

Response

{
  "data": {
    "watchlist": [
      {
        "page_id": "2218331548432159",
        "name": "Epycure",
        "shop_domain": "epycure.com",
        "added_on": "2026-11-13"
      }
    ],
    "max": 25
  },
  "meta": {
    "endpoint": "watchlist_edit",
    "api_version": "1.22.2",
    "credits_charged": 0,
    "credits_left": 1115,
    "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."
  }
}