watch_competitor

Start watching a competitor’s ads (the Creative Studio’s Inspiration › Competitors) and kick off the first pull.

Billing: adding a competitor charges the organization’s flat ad-intel sync credit — call this only when the user explicitly wants to track the company. Requires the plan’s creative_management feature.

Requires a user-bound credential (OAuth login or a personal API key): the charge and the watch-list change are attributed to that person (added_by). Anonymous organization API keys get error_type: "user_credential_required".

Ads fill in asynchronously after the pull completes (typically minutes); poll list_competitor_ads.

Provide the company name; when domain is omitted it is resolved automatically from the name, and the call errors (instead of creating a dead watch) if no website can be found.

Parameters#

Returns#

{
  "success": true,
  "competitor": {
    "id": 42,
    "name": "Acme Corp",
    "domain": "acme.com",
    "role": "inspiration",
    "ad_count": 0,
    "platforms": [],
    "last_pulled_at": null,
    "is_pulling": true
  },
  "note": "Watch added; the first ad pull runs asynchronously (the org's flat sync credit was charged). Poll list_competitor_ads in a few minutes.",
  "source": "adlyse.brand_watch@v1"
}

Errors#