Competitor Ads

Overview

Add up to 10 competitor Facebook pages per client. Mythic scrapes each page's Meta Ad Library ads once a day, or now when you ask, and keeps every ad it has seen.

For every ad Mythic:

1. Stores the copy, headline, call to action, landing link, format, platforms and Ad Library start date, plus the full scraped row.
2. Copies the images and video to Mythic storage. Ad Library media links expire after about five days; Mythic's copies do not.
3. Transcribes the video with sentence timestamps. A video shared by several ads or clients is transcribed once.
4. Reads the ad and its transcript with two Cloudflare models. One quotes the hook, intro, problem, mechanism, offer and call to action, and gives the video seconds where each one is spoken. The other tags the hook type, persuasion angle and offer elements.

The summary then answers what each competitor runs: formats, new ads in the last 7 and 30 days, which hooks, angles and offers they use most, and which active ads have run longest. Days running is the only public signal of a winning ad: advertisers keep paying for ads that work.

Base URL

https://mythic-analytics.gulp.workers.dev/client/v1/competitor-ads

The same key system as the rest of /client/v1: an agency key (ak_, which must bind a location on every request with ?location_id= or the X-Location-Id header) or a location secret key (sk_, auto-scoped to its own location). An agency key that binds no location returns 400 location_required; one that names a location it is not linked to returns 403 location_not_linked.

A location secret key (sk_) can read pages, ads and the summary. Adding, changing, refreshing and deleting pages needs an agency key or an mcp_ key with competitor_ads:write. Reads with an mcp_ key need competitor_ads:read.

This surface is sold by tier. If your plan does not include it, every endpoint answers 402 feature_not_in_plan — the key is valid, the tier is what is missing. GET /client/v1/agency/quota lists what your plan includes.

Competitor ads is part of the Pro plan. Pausing a page (PATCH /pages/{id} with only active: false) and deleting one work on every plan.

Track a page

Find the page id in the Ad Library URL (view_all_page_id=64841063928).

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/competitor-ads/pages?location_id=LOC" \
  -H "Authorization: Bearer ak_..." -H "Content-Type: application/json" \
  -d '{"page_id": "64841063928", "label": "Juvenon", "country": "US", "max_ads": 50}'

The first scrape runs within 5 minutes. POST /pages/{id}/refresh runs it now and waits for it (up to about a minute for 50 ads). It answers:

• 429 refreshed_recently within 10 minutes of the last scrape of that page for this client.
• 429 refresh_budget_exhausted after 20 manual refreshes by this client in 24 hours. Pages still refresh daily.
• 409 refresh_in_progress while a refresh runs.

Deleting and re-adding a page, or pausing and resuming it, does not reset these limits. A re-added or resumed page is first refreshed 24 hours after its last scrape.

Processing

A refresh stores the ads at once. Media copies, transcripts and analysis follow in the background, usually within a few minutes. Each ad shows its progress:

• media_status: pending, done, partial (some files failed), failed, none (no media).
• analysis_status: pending, done, failed. Video ads are analysed after their transcript is ready.

A changed ad copy or headline is analysed again. New media is copied again.

Read ads

GET /ads lists one row per ad, or per card for carousel and dynamic (DCO) ads, newest start date first.

Page with limit (up to 200) and next_cursor.

Landing pages

Every ad carries landing_page: { url, domain, path }, the link_url Meta shows, normalized so ads that send people to the same page group together:

• Tracking parameters are removed: utm_*, hsa_*, fb_*, fbclid, gclid, gbraid, wbraid, dclid, msclkid, ttclid, twclid, yclid, igshid, li_fat_id, mc_cid, mc_eid, _ga, _gl, _hsenc, _hsmi, mkt_tok, irclickid, epik, sscid. Other parameters, such as variant or id, are kept and sorted by name.
• The scheme and host are lowercase. The fragment, credentials, default port and trailing slash are dropped.
• domain is the host without www..
• Redirect links, such as link.juvenon.com/xxxl-men-fb, are shown as Meta shows them. They are not followed.
• Cards of a carousel or dynamic ad often share one landing page.

landing_page is null when the ad has no http(s) link.

GET /ads/{id} adds the transcript, the full analysis and media links. ?include=raw adds the scraped Ad Library row.

Media links

thumbnail_url and each media[].url are signed links valid for about an hour. They work in <img> and <video> tags without a key and support range requests. Read the ad again for fresh links. Videos larger than 100 MB, or larger than 32 MB when the CDN sends no file size, are not copied and show skipped: "too_large".

Analysis

{
  "taxonomy_version": 2,
  "has_transcript": true,
  "fields": {
    "hook": { "text": "This is what happens to a man's body when he takes nitric oxide boosters every single day for 30 days straight.", "confidence": 0.76, "source": "transcript", "start_s": 0, "end_s": 5.98 },
    "offer": { "text": "60-day money-back guarantee", "confidence": 0.81, "source": "transcript", "start_s": 80.1, "end_s": 84.2 },
    "cta": { "text": "Grab them before they're gone.", "confidence": 0.5, "source": "transcript" }
  },
  "hook_start_s": 0,
  "hook_end_s": 5.98,
  "tags": { "hook_type": ["story"], "angle": ["authority_science"], "offer": ["guarantee"] },
  "probabilities": { "offer": { "guarantee": 0.947, "discount": 0.08 } }
}

• fields: hook, intro, problem, mechanism, offer, cta. Each is quoted from the ad copy or transcript, or null when the ad has none. source says where it was found. Text from the video carries start_s and end_s.
• tags: every tag with probability 0.5 or more. probabilities keeps all of them.

taxonomy_version changes when the tag set or the E.P.I.C. test changes. Stored analyses with an older version are analysed again in the background, after new ads. Until the new analysis fully succeeds, the ad keeps its current analysis, and an upgrade that fails three times leaves it on the older version.

E.P.I.C. test

analysis.epic applies Chris Rocheleau's publicly described E.P.I.C. long-copy formula: Engage, Present, Illustrate, Convert. The rule wording and scoring are Mythic's own interpretation of his public descriptions. They are not yet checked against spend results, so there is no overall score. rules_followed counts the rules an ad meets and lists them.

{
  "copy": { "words": 126, "you_top_half": 3, "you_bottom_half": 0 },
  "you_only_bottom_half": false,
  "checks": { "engage.direct_question": 0.0365, "engage.mechanism_in_opener": 0.7146, "convert.cta": 0.8764 },
  "stages": {
    "copy": {
      "labels": [{ "i": 1, "stage": "E", "p": 0.5884 }, { "i": 2, "stage": "E", "p": 0.3328 }, { "i": 3, "stage": "I", "p": 0.3887 }],
      "sequence": "EIPIC", "stages_present": "EPIC", "in_order": false, "all_stages_in_order": false,
      "paragraphs_total": 7, "paragraphs_assessed": 7, "truncated": false
    }
  },
  "all_stages_in_order": false,
  "rules_followed": { "met": 7, "total": 16, "rules": [{ "rule": "not:engage.direct_question", "met": true }] },
  "input_tokens": 5072,
  "cost_usd": 0.00019274
}

• copy, transcript: word count and the number of "you", "your", "you're", "yours" and "yourself" in the top and bottom half. His rule is no "you" until the bottom half.
• checks: probability that each of 14 rules applies. Engage: direct_question, indirect_open, negative_callout, pain_and_benefit_in_opener, mechanism_in_opener. Present: struggle, empathy. Illustrate: journey, teaches_value, differentiation, substantiated, lead_is_other_persons_story. Convert: cta, risk_reversal. direct_question, negative_callout and lead_is_other_persons_story break a rule when they apply.
• stages: copy, and transcript for video ads. Each paragraph takes its most likely stage when that probability is 0.3 or more, else -. The ad copy and the video transcript are separate sequences. sequence collapses repeats, in_order means it never goes back to an earlier stage. Copy or transcript under 40 words is not labeled (skipped).
• Only the first 30 paragraphs of a sequence are labeled. paragraphs_total, paragraphs_assessed and truncated say so. A truncated sequence has in_order and all_stages_in_order null (unknown), unless a reversal was already seen (false).
• all_stages_in_order (top level): true when the copy or the transcript is known to have all four stages in order. Otherwise null when either is unknown (labelling failed, skipped, or truncated), and false only when every present sequence is known not to. null is never counted as a negative.
• rules_followed: the "you" rule, each check (met at 0.5 or more, or under 0.5 for the three that break a rule) and all_stages_in_order when it is not null.
• A part that fails stores error (checks_error for the checks, with checks_input_tokens when the call was billed). Its tokens still count in input_tokens and cost_usd. The rest of the analysis is kept.

GET /ads rows carry epic: { all_stages_in_order, rules_met, rules_total }.

Summary

GET /summary (optional page_id) returns overall and one entry per tracked page. Counts are per ad: a three-card carousel is one ad, carrying a tag when any of its cards does. Tag shares are over analysed ads only.

Ad prompts

POST /ad-prompts writes 1-5 ad briefs for the client from its brand and its competitors' working ads: ads that have run 30 days or more, weighted by days running, with active ads counted over stopped ones. Ads under 30 days are shown to the model as new tests and are never evidence. When the client's plan includes creative analysis, its top 5 active own ads by 90-day spend join the grounding with their hooks, tags and E.P.I.C. result, and prompts may cite them by ad_id in own_creative_ids. Own ads are ranked by spend only: no cost per result is stored for them. An mcp_ key also needs creative_analysis:read; without it own ads are left out (own_creatives.reason: insufficient_scope). Send "include_own_creatives": false to leave them out yourself.

The grounding is at most 45,000 characters. Every text field is cut, then new tests, own ads, the summary and lower-ranked working ads are dropped in that order (dropped_for_size). When the ad to rewrite and the top working ad alone do not fit, the call fails with 422 grounding_too_large before any model call.

It runs on the agency's own model key, the same key as scouts: Mythic pays for no model call, and a client with no key gets 409 no_model_key. Write scope (competitor_ads:write or an agency key), 20 per client per rolling 24 hours, failed calls included. A call can take a few minutes.

Save the brand once with PUT /brand (product is required; audience, benefits, angles, proof, offers, must_avoid, compliance are optional), or send brand in the request to use it for that call only.

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/competitor-ads/ad-prompts?location_id=$LOC" \
  -H "Authorization: Bearer $AK" -H "Content-Type: application/json" \
  -d '{"count": 2, "formats": ["copy", "image", "video", "ugc", "rewrite"]}'

Each prompt has:

Before it is returned, every answer is checked:

• It matches the prompt schema for the requested formats.
• Every cited id is in the grounding (grounding.competitor_ad_ids, own_creative_ids, rewrite_ad_id). Only working ads may be cited as sources.
• Each rewrite section's original is the selected ad's text, quoted verbatim (pieces may be joined with ...; every piece is checked, and an empty original is refused).
• The headline, hook, primary text, video script and rewrite follow the E.P.I.C. rules: no direct self-identification question ("Are you...?"), no "you" in the top half, no negative call-out of the reader, and the stages E, P, I, C all present and in order.

An answer that fails gets one repair turn with the errors; a second failure returns 502 generation_invalid with the errors in details. The response reports the provider, the model and token usage. usage.cost_usd is the total when every call reported a cost (OpenRouter does; Gemini and Cloudflare do not). When any call did not, including a call that timed out or hit a network error after it was sent, cost_usd is null, usage_complete is false, and cost_usd_known is the cost of the calls that did report one.

record.saved says whether the generation's status and usage were stored, and record.prompts_saved whether the prompts were. The prompts are returned either way, since the model was already paid for. Model errors name the category and the provider's HTTP status only; the provider's text is never returned.

Errors

MCP tools

list_competitor_pages, add_competitor_page, update_competitor_page, delete_competitor_page, refresh_competitor_page, list_competitor_ads, get_competitor_ad, get_competitor_ads_summary, get_competitor_ad_brand, set_competitor_ad_brand, generate_ad_prompts. See MCP tools.