Changelog

The API is versioned in its paths (/v1/…). Inside v1, changes only add things: a new field, endpoint, filter or tool. Nothing is renamed or removed in v1. A breaking change would get /v2/, with v1 kept running alongside it. Every answer carries its version in the Poseidon-API-Version header and in meta.api_version.

1.2.0 (12/11/2026, night): the Ask box

  • GET /v1/ask/options and POST /v1/ask: a no-code box for people. Pick a niche, a country, an optional format and a goal (top winners, winning hooks, A/B test winners), and get the real answer written for humans. No language model is involved. With a key it costs what the call costs (5 credits, 0 if nothing matches). Without a key: 3 free tries per visitor address a day (a try that finds nothing isn't counted), 3,000 a day in all.
  • The Ask box answers only for niche x country pairs that Growth checked by hand. An ad counts for a niche when its own text, title or landing page names it (word lists in 7 languages), its landing site is a shop approved by hand for that niche, and the country holds the biggest part of its breakdown. A/B tests: an approved shop, a version whose text names the niche, a best ad with 10,000+ EU reach. Advertisers are named by their shop's website, never by their Facebook page name. Country names (France first), format names, a caption per goal. Answers are prepared in the background, so most come back in well under a second.
  • Embeddable component: <poseidon-ask></poseidon-ask> plus <script src="https://api.askposeidon.app/embed/ask.js" defer>. Demo page: /embed/demo.html.
  • Usage rows now say the call type (search, full_ad, brand_view, weights_query, ab_tests) and the credits charged.

1.1.0 (12/11/2026, evening): reach shown by Meta's own total only

A correction, applied the same day the API went public. Meta's age x gender x country rows don't add up to Meta's EU total (measured on 3,820 reads: 0.93x to 1.10x of it; a single country was above the whole EU total in 1,416 reads). So a country or segment figure in people was not a fact, and it is gone.

  • The only number of people is Meta's EU total: eu_reach.total, labelled "EU reach (Meta's total)".
  • Countries, ages and genders are shares of Meta's breakdown of the same read, from 0 to 1: eu_reach.country.share_of_meta_breakdown, eu_reach.segment.share_of_meta_breakdown and share_within_country (search, A/B tests); country_share_history and age_gender_share_latest (one ad); and share_of_meta_breakdown_in_country (niche pages).
  • Removed: eu_reach.country.reach, eu_reach.segment.reach, by_country_history, age_gender_latest (people), and median_country_reach on niche pages.
  • Filters: min_country_share and min_segment_share (0 to 1) replace min_country_reach and min_segment_reach, which now answer 400 with an explanation. Sorts: country_share and segment_share; the old names country_reach and segment_reach still work as aliases. With a country, age or gender, the default sort is eu_reach.
  • Weights and ranks: only the formula versions weight-v2 and rank-v2 (reach signal = Meta's EU total; country as a share). Weights now return real rows.

1.0.0 (12/11/2026)

First version. Public since 12/11/2026 at https://api.askposeidon.app (Cloudflare tunnel; MCP at /mcp).

  • Endpoints: GET /v1/filters, /v1/winners, /v1/ads/{ad_id}, /v1/brands/{page_id}, /v1/brands?domain=, /v1/weights, /v1/account, /v1/packs, POST /v1/checkout, GET /v1/checkout/{session_id}, POST /v1/stripe/webhook.
  • MCP server at POST /mcp (streamable HTTP, JSON answers). Tools: filters, search_winners, get_ad, get_brand, get_weights, account.
  • Every number carries the day it was read and its source. A value Poseidon doesn't have is left out, never filled in. Aggregates (weights, a brand's median days live) are hidden below the minimum sample of 30 ads.
  • Search results say how many matching ads have a transcribed script (matching_ads_with_script).
  • Sources are given in public words ("Meta Ad Library (public ad page, read by Poseidon)", "speech-to-text (Whisper)", "AI section labelling (Claude Fable)"), not internal file names.
  • Links only, never media: the Ad Library link, the shop link and the landing link.
  • Prepaid credits that never expire (1 credit = €0.01): search 5, full ad 2, brand 5, weights 10, filters and account free. A call that returns nothing costs 0; errors are never billed.
  • Packs via Stripe Checkout: €20 = 2,000 credits, €50 = 5,500, €200 = 24,000. The first 20 paid purchases get +50%. Test mode only so far.
  • Brands' own A/B tests: GET /v1/experiments and the MCP tool search_experiments (5 credits). Same video with different texts, same text with different videos, same script with a different hook; each variant with its ads, reach and measured outcome. The shared video file is never served.
  • Early-access list: POST /v1/early-access (email kept for the launch confirmation email; same answer either way).
  • Launch bonus: the first 20 paying buyers get +50% credits on their first pack, added when the payment is confirmed.
  • Free public niche pages: GET /v1/public/niche-pages and /v1/public/niche-pages/{niche}/{country}, no key, cacheable; every ad shown is checked against the base when the pages are built.
  • Speed: answers are gzip-compressed (a search is about 5 times smaller), daily data is cached in memory, keyed answers say Cache-Control: no-store and public ones public, max-age=300. When the server is full it answers 503 with Retry-After: 2 instead of dropping the connection. limit on /v1/experiments is 1 to 20.
  • Free trial: POST /v1/keys with an email gives a key with 100 credits (€1). One per email, 3 per IP address a day, 200 a day in all. Only hashes of the email and IP are kept; the email is not verified.
  • Discovery for agents: /openapi.json, /llms.txt, /.well-known/mcp.json, and / (an index).
  • Limits protect the server: per key 3 requests a second (bursts of 15); per IP address 10 a second (bursts of 40); wrong keys slowed down after 12 a minute per IP; 32 connections at once; 64 KB bodies; 8 seconds at most per query; 50 rows per page. Hot queries are cached for 2 minutes (each call is still billed).
  • Browser calls (CORS) are allowed from askposeidon.app only, for packs, checkout and trial keys; the public documents are open to all.