Quickstart

Ask "give me a winning format, go look" and get real ads back: the Ad Library link, days live, EU reach by country and age x gender, versions, the shop behind the ad, and the verbatim script cut into sections.

1. Get an API key

Keys look like psd_…. Get your free key: an email gives you a key with 100 credits, shown once. 

export POSEIDON_API_KEY=psd_...
export POSEIDON_URL=https://api.askposeidon.app

2. Make your first call

Search winning ads. Send your key as a Bearer token.

curl -s -H "Authorization: Bearer $POSEIDON_API_KEY" \
  "$POSEIDON_URL/v1/winners?niche=weight%20loss&country=FR&format=VIDEO&limit=3"

Python

import json, os, urllib.parse, urllib.request
q = urllib.parse.urlencode({"niche": "weight loss", "country": "FR", "format": "VIDEO", "limit": 3})
req = urllib.request.Request(f"{os.environ['POSEIDON_URL']}/v1/winners?{q}",
                             headers={"Authorization": f"Bearer {os.environ['POSEIDON_API_KEY']}"})
r = json.load(urllib.request.urlopen(req))
for ad in r["data"]["results"]:
    print(ad["library_url"], ad["days_live"], "days", ad.get("eu_reach", {}).get("total"))
print("credits left:", r["meta"]["credits_left"])

JavaScript

const q = new URLSearchParams({ niche: "weight loss", country: "FR", format: "VIDEO", limit: "3" });
const res = await fetch(`${process.env.POSEIDON_URL}/v1/winners?${q}`, {
  headers: { Authorization: `Bearer ${process.env.POSEIDON_API_KEY}` },
});
const r = await res.json();
for (const ad of r.data.results) console.log(ad.library_url, ad.days_live, "days", ad.eu_reach?.total);
console.log("credits left:", r.meta.credits_left);

3. What comes back

Every number carries the day it was read and its source. A value Poseidon doesn't have is absent from the answer, never filled in. Aggregates (weights, a brand's median days live) are not returned below the minimum sample of 30 ads. Links only, never media. No search by person name.

A winner is an ad live for at least 21 days: days between Meta's start date and its stop date, or our last read if it is still active. Override with min_days_live.

Next: one ad in full, or use Poseidon from your agent. The full spec: openapi.json.