GET /v1/watchlist/changes

What changed across all your watched brands since a date

What changed across ALL your watched competitors since a date, in one call. Use it for 'what's new from my competitors', 'weekly competitor report'. Same content, dates and sources as brand_changes, grouped by brand; brands with no change are listed apart. Also says how many watched ads have at least two reach readings since the date (reach growth can only be shown for those). Costs 5 credits per brand that changed; 0 if none did.

Cost: Free.

Parameters

Parameter	Type	What it does
`since`	string	default: 7 days ago

Errors

`400`	A parameter is refused (the answer lists the accepted values). Not billed.
`401`	Missing, unknown or revoked API key.
`402`	Not enough credits for this call. Credits never expire; top up with a pack.
`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/watchlist/changes?since=2026-11-01" \
  -H "Authorization: Bearer $POSEIDON_API_KEY"

Response

{
  "data": {
    "since": "2026-11-01",
    "watched_brands": 1,
    "brands_with_changes": [
      {
        "brand": {
          "page_id": "2218331548432159",
          "name": "Epycure",
          "shop_domain": "epycure.com"
        },
        "since": "2026-11-01",
        "started": [],
        "stopped": [
          {
            "ad_id": "1846559006694732",
            "library_url": "https://www.facebook.com/ads/library/?id=1846559006694732",
            "stopped": "2026-11-13",
            "started": "2026-10-31",
            "days_live": 13,
            "source": "Meta's stop date"
          },
          {
            "ad_id": "1019162297879814",
            "library_url": "https://www.facebook.com/ads/library/?id=1019162297879814",
            "stopped": "2026-11-13",
            "started": "2026-10-31",
            "days_live": 13,
            "source": "Meta's stop date"
          }
        ],
        "more_versions": [],
        "relaunched_media": [],
        "reach_movers": [],
        "reach_movers_coverage": {
          "ads": 30,
          "ads_with_2_reach_readings_since": 0,
          "note": "reach growth can only be shown for ads read at least twice after 'since'"
        }
      }
    ],
    "brands_without_changes": [],
    "reach_movers_coverage": {
      "watched_ads": 30,
      "watched_ads_with_2_reach_readings_since": 0,
      "note": "reach growth can only be shown for ads read at least twice after 'since'"
    },
    "coverage": "Started and stopped come from Meta's own dates; version changes and reach growth from Poseidon's readings (history since 12/11/2026)."
  },
  "meta": {
    "endpoint": "watchlist_changes",
    "api_version": "1.22.2",
    "credits_charged": 5,
    "credits_left": 1110,
    "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."
  }
}