> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration. ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** ## API base URL and authentication - **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev` - **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route). - **OpenAPI JSON:** ## Recommended docs entrypoints (this site) - [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown). - [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope. - [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`. - [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages. - [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples. - [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths. - [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install. - [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 240 endpoint tools, plus docs_search/docs_read for implementation help. - [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples. - [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start. - [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog. - [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI). - [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls). - [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist. - [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping. - [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages. - [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance. - [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs. - Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract. ## Markdown docs convention - Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`). - Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`). - Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`). --- # Ad Tracker events (https://www.socialfetch.dev/docs/monitors/ad-tracker-events) The [Competitor Ad Tracker](/competitor-ad-tracker) can send its alerts to the same webhook endpoints monitors use. Pick the endpoints in the app under **Tools → Ad Tracker → Settings → Webhooks**. Each endpoint you pick gets all four event types. Delivery works exactly like monitor events: the same [signature](/docs/monitors/webhooks), the same [retries and idempotency](/docs/monitors/delivery-retries), and the same delivery log on the endpoint's page. Dedupe on `socialfetch-event-id`. ## When they're sent | Type | Sent when | | -------------------------- | ------------------------------------------------------------------------------------------------------------- | | `ad_tracker.ads.launched` | A daily check of one competitor on one library finds new ads. One event per competitor per library per check. | | `ad_tracker.ads.stopped` | The same check finds ads that stopped running. | | `ad_tracker.brief.ready` | A competitor's monthly brief is written. | | `ad_tracker.digest.weekly` | Monday morning, when the workspace's week had any launches, stops or new countries. | Webhooks don't follow the email settings. There's no daily cap and no "only once N new ads" minimum: every check that finds something sends an event. A competitor's first check (which collects its existing ads) sends no `ads.launched`, because those ads aren't new launches. ## The envelope An Ad Tracker event is a monitor event's envelope without `monitor`, `source` and `billing`. Tracker events cost nothing beyond the checks themselves. ```json { "id": "evt_…", "apiVersion": "2026-08-01", "type": "ad_tracker.ads.launched", "createdAt": "2026-10-10T07:12:44.000Z", "data": { "summary": "Gymshark launched 12 new ads on Meta", "url": "https://app.socialfetch.dev/tools/ad-tracker/competitors/adc_…", "competitor": { "id": "adc_…", "name": "Gymshark", "website": "gymshark.com", "url": "https://app.socialfetch.dev/tools/ad-tracker/competitors/adc_…" }, "library": "meta", "libraryName": "Meta", "count": 12, "truncated": true, "ads": [ { "id": "ada_…", "url": "https://app.socialfetch.dev/tools/ad-tracker/ads/ada_…", "library": "meta", "externalId": "1234567890", "format": "video", "headline": "New season, new PBs", "body": "Our lightest training set yet.", "callToAction": "Shop now", "destinationUrl": "https://www.gymshark.com/", "libraryUrl": "https://www.facebook.com/ads/library/?id=1234567890", "mediaUrl": "https://…", "countries": ["US", "GB"], "startedAt": "2026-10-09T00:00:00.000Z", "firstSeenAt": "2026-10-10T07:12:40.000Z", "stoppedAt": null } ] } } ``` Every `data` has `summary`, one plain sentence, and `url`, the matching page in the app. Missing values are `null`, never left out, and times are ISO strings. * **`ads.launched` / `ads.stopped`:** `count` is every ad found; `ads` lists up to 10, newest first, and `truncated` says whether there were more. `mediaUrl` is the library's own link and can expire, so open the ad's `url` for the archived copy. * **`brief.ready`:** `brief` has `periodStart`, `periodEnd`, `adsConsidered` and `pointCount`. The brief is an AI summary, so it stays in the app; open `url` to read it. * **`digest.weekly`:** `periodStart`, `periodEnd`, `totals` (`newAdCount`, `stoppedAdCount`), `competitors` (busiest first, each with its counts, `countriesStarted` and `longestRunning`), and `more` for the competitors left out of the list. A test event from **Send test event** is a real `ad_tracker.ads.launched` with sample data and `"sample": true` on the envelope. ## Typed in the SDK ```ts import { constructEvent, type WebhookEvent } from "@socialfetch/sdk/webhooks"; const event = await constructEvent({ payload, signatureHeader, secret: process.env.SOCIALFETCH_WEBHOOK_SECRET!, }); if (event.type === "ad_tracker.ads.launched") { console.log(event.data.summary, event.data.ads.map((ad) => ad.url)); } ``` `WebhookEvent` covers monitor and Ad Tracker events. Use `AdTrackerEvent` if the endpoint only gets tracker events. `AD_TRACKER_EVENT_TYPES` lists the four types. ## Slack, Teams and spreadsheets Endpoints receive signed JSON, which Slack's and Teams' incoming webhooks don't accept as it is. Use Zapier or Make in between: 1. Create a **Catch Hook** (Zapier's Webhooks trigger) or a **Custom webhook** (Make) and copy its URL. 2. Add it as a webhook endpoint in SocialFetch and turn it on under the Ad Tracker's webhook settings. 3. Click **Send test event** so Zapier or Make can see the fields. 4. Post `data.summary` and `data.url` to a Slack or Teams channel, or add a row per ad from `data.ads` to a sheet. ## Build on it with the API Each ad library the tracker reads is also an API endpoint, billed in the same credits: [Meta company ads](/docs/api/v1/facebook/ad-library/companies/ads/get), [LinkedIn ad library search](/docs/api/v1/linkedin/ad-library/ads/search/get), [Google company ads](/docs/api/v1/google/ad-library/companies/ads/get) and [TikTok ad library search](/docs/api/v1/tiktok/ad-library/ads/search/get). Call them yourself, or [create a monitor](/docs/monitors/quickstart) on any watchable endpoint.