Quickstart: your agent's first Facebook Ad Library call

From zero to your first ads in two minutes. Your agent can do almost all of this itself. The one step it can't is approving the sign-in in your browser. That's on purpose.

Agents: this page is also at adsentinel.eu/docs/quickstart.md

Let your agent set it up

Paste this into a terminal agent

Set up AdSentinel so you can get Meta Ad Library ads for me.

1. Read https://adsentinel.eu/docs/quickstart.md
2. Run `npx adsentinel login` and show me the link it prints.
   I'll approve it in my browser.
3. Add the MCP server `npx -y adsentinel mcp` to your config,
   or use the `adsentinel` CLI if you have a shell.
4. Test it for free: look up the advertiser "Zalando" in Spain
   and show me the candidates. Don't fetch any ads yet.

Paste it into an agent that runs in a terminal, such as Claude Code, Codex, Hermes or Gemini CLI. Not into a chat window: the agent has to run commands.

Claude Code

Install the plugin

/plugin marketplace add adsentinel-eu/adsentinel
/plugin install adsentinel@adsentinel

Adds the tools, a skill that knows how to use them, and two commands: /adsentinel:advertiser and /adsentinel:keyword.

Or do it yourself

  1. Sign in

    Opens your browser once. New accounts get €2 of free credit.

    npx adsentinel login

  2. Connect your agent

    Pick the one that fits. They all call the same API with the same key.

    Any MCP client

    {
  "mcpServers": {
    "adsentinel": {
      "command": "npx",
      "args": ["-y", "adsentinel", "mcp"]
    }
  }
}

    Uses the key from adsentinel login. On a machine without it, add "env": {"ADSENTINEL_API_KEY": "…"}.

    A shell, a script or cron

    adsentinel advertiser zalando --country ES --max 50
adsentinel keyword "sneakers" --country FR --out sneakers.csv

    HTTP

    curl https://api.adsentinel.eu/v1/advertisers?q=zalando&country=ES \
  -H "Authorization: Bearer $ADSENTINEL_API_KEY"

  3. Ask

    In plain words. The agent looks the brand up, asks you which page you mean, then fetches its ads.

    you    What is Loop Earplugs running in Germany right now?
agent  Several pages match. Which one do you mean?
       1  Loop           · @loopearplugs · 118.8k likes
       2  Loop earplugs  · 27 likes
you    1
agent  40 ads, all launched today, mostly Loop Switch™ earplugs…

What your agent gets back

A summary first, then the ads. The first line always says what to do next, so an agent never mistakes a partial result for a complete one. Same price in every size: pick the one that fits your agent's context. Below: 40 real Walmart US ads, first rows shown.

{"next":"Done: the 40 newest ads; more exist beyond maxAds. If your user needs more, a new call with a higher maxAds bills every ad again. The whole result as a spreadsheet (CSV, link valid 1 hour): https://api.adsentinel.eu/v1/jobs/cca88e1e-13f2-4a0b-bb5a-4b40e1fcfa0d/download?format=csv&projection=default&a=e729a077-de10-418e-968c-7c6949bb936d&v=1&expires=1791493312&sig=PqdPISmkXkz5Qqb5EBzGQl6zZk-3KYceHNQmqr3Rnvk. Give your user this link when they want to keep or share the ads; get_job gives a fresh link later.","schemaVersion":"1","jobId":"cca88e1e-13f2-4a0b-bb5a-4b40e1fcfa0d","kind":"advertiser","status":"completed","stoppedBy":"maxAds","query":{"kind":"advertiser","maxAds":40,"country":"US","newOnly":false,"variants":false,"euInsights":true,"activeStatus":"active","advertiserIds":["159616034235"]},"dataAsOf":"2026-10-08T20:01:36.209Z","expiresAt":"2027-01-06T20:01:51.165Z","billed":{"ads":40,"eur":0.1596},"advertisers":[{"advertiserId":"159616034235","name":"Walmart","verification":"BLUE_VERIFIED","returned":40,"exhausted":false}],"ads":40,"active":40,"startedBetween":["2026-10-07","2026-10-08"],"platforms":{"FACEBOOK":36,"INSTAGRAM":25},"mediaTypes":{"card":81,"video":4},"displayFormats":{"DCO":36,"VIDEO":4},"dcoShare":0.9,"euEligible":0,"euInsightsAvailable":0,"euInsightsNote":"EU insights exist only for ads shown in an EU/EEA country; with country \"US\" none were fetched, so each ad reads not_eligible or not_requested.","takenDown":0,"creativesTotal":85,"landingDomains":[{"ads":39,"domain":"walmart.com"},{"ads":1,"domain":"mavely.app.link"}],"launchesByWeek":{"2026-10-05":40},"longestRunning":[{"adId":"1621493136337067","runningDays":2},{"adId":"2296464551084715","runningDays":2},{"adId":"955160157662630","runningDays":2}],"permalink":"https://www.facebook.com/ads/library/?id=<id>","permalinkExample":"https://www.facebook.com/ads/library/?id=2296464551084715","page":{"from":0,"ads":40,"of":40},"cursor":null,"download":{"jsonl":"https://api.adsentinel.eu/v1/jobs/cca88e1e-13f2-4a0b-bb5a-4b40e1fcfa0d/download?format=jsonl&projection=default&a=e729a077-de10-418e-968c-7c6949bb936d&v=1&expires=1791493312&sig=L-8dpAkNhxaQZm7DpBV07xVL0OKM2B2K-MuKHM6yIBo","csv":"https://api.adsentinel.eu/v1/jobs/cca88e1e-13f2-4a0b-bb5a-4b40e1fcfa0d/download?format=csv&projection=default&a=e729a077-de10-418e-968c-7c6949bb936d&v=1&expires=1791493312&sig=PqdPISmkXkz5Qqb5EBzGQl6zZk-3KYceHNQmqr3Rnvk"}}

id,startedAt,lastSeenActiveAt,isActive,runningDays,platforms,creativeCount,gatedType,euInsights,advertiserId,endedAt,euTotalReach,copyKey,assetKey
2296464551084715,2026-10-07,2026-10-08,true,2,INSTAGRAM,1,ELIGIBLE,not_eligible,159616034235,,,not_requested,not_requested
1621493136337067,2026-10-07,2026-10-08,true,2,INSTAGRAM,1,ELIGIBLE,not_eligible,159616034235,,,not_requested,not_requested
955160157662630,2026-10-07,2026-10-08,true,2,INSTAGRAM,3,ELIGIBLE,not_eligible,159616034235,,,not_requested,not_requested

… 37 more ads

adId,type,title,body,cta,linkUrl,n
2296464551084715,video,,"#WalmartPartner | 6 fall denim fits, 6 places I’d actually wear them. Errand day, date night, museum, city shopping, office and weekend hang. Didn’t expect to build all 6 out of one Walmart run, but here we are. Which fit are you trying out first?",Shop now,https://www.walmart.com/cp/the-denim-shop/9468715,1
1621493136337067,video,,#walmartpartner Fall outfits are officially my favorite thing to shop for 🍂 Which look is your favorite? Shop these plaid fits and more at Walmart.com or on the app @walmart,Shop now,https://www.walmart.com/shop/womens-trends,1
955160157662630,card,,"New season, new classics—for her & him. From Free Assembly. Only at Walmart.",Shop Now,https://www.walmart.com/shop/clothing-and-accessories/free-assembly,3

… 37 more ads

adId,i,type,url
2296464551084715,0,video,https://video-mrs2-2.xx.fbcdn.net/o1/v/t2/f2/m367/AQM8WvyDIF5-iOBkpstNFNzu__yGkG0rWisAq_1qNceYq6fyPJSEiX3iJDVZW2FL_X-6IeTcSEIIIRjeeerfGeNWzZnEWmrtmlVdlrjexg.mp4?_nc_cat=107&_nc_sid=ef5aa3&_nc_ht=video-mrs2-2.xx.fbcdn.net&_nc_ohc=XIL4TNv3_TIQ7kNvwEZ82WA&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl8zNjBwIiwieHB2X2Fzc2V0X2lkIjoyMDg5MjI0OTcxNjk3OTQxLCJhc3NldF9hZ2VfZGF5cyI6MjEsInZpX3VzZWNhc2VfaWQiOjEyMzc0LCJkdXJhdGlvbl9zIjo0MiwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=AAKPvVbhpicU1KWnu0QBTg&_nc_ss=7e289&_nc_zt=28&oh=00_AQPrd2g-DLTwPk2R7ewAN_tOyd_82V3s4iTPV4f--MHWHQ&oe=6ACDB4DF
1621493136337067,0,video,https://video-mrs2-1.xx.fbcdn.net/o1/v/t2/f2/m367/AQPKbhwy3u9UW5tscgxSvfnpVwV5_Gn_lBf2orvOVI-fGetYSqULXcSaqXONX_xQ_leSoI6SjrFkZloUe2Mgdw8A284eHEwYfETOXggMoA.mp4?_nc_cat=105&_nc_sid=ef5aa3&_nc_ht=video-mrs2-1.xx.fbcdn.net&_nc_ohc=3rhfoTja99YQ7kNvwH635x-&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnByb2dyZXNzaXZlX2gyNjQtYmFzaWMtZ2VuMl8zNjBwIiwieHB2X2Fzc2V0X2lkIjoyODM4NDQzNTA2NzkwNTA0NiwiYXNzZXRfYWdlX2RheXMiOjEwLCJ2aV91c2VjYXNlX2lkIjoxMjM3NCwiZHVyYXRpb25fcyI6MzEsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&_nc_gid=AAKPvVbhpicU1KWnu0QBTg&_nc_ss=7e289&_nc_zt=28&oh=00_AQM8oxAUmsLURWIvqXl37csu61MP6SofaEqJXQ8wlbzQ7Q&oe=6ACDBFA5
955160157662630,0,video,https://video-mrs2-1.xx.fbcdn.net/o1/v/t2/f2/m412/AQMo7HeLdyK4Db5BhEr38bER4lKAlYkOuusWfg7pb_fVTFL_ywhkr2Zs2VbEqb16pAHwHq6kd6-JqiAixVjNqosYy9hT7B37h41EUV3_uQ.mp4?_nc_cat=100&_nc_sid=ef5aa3&_nc_ht=video-mrs2-1.xx.fbcdn.net&_nc_ohc=9vPA7Du0NgsQ7kNvwHOgiON&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5WSV9VU0VDQVNFX1BST0RVQ1RfVFlQRS4uQzMuMzYwLnN2ZV9zZCIsInhwdl9hc3NldF9pZCI6MTU5OTU1MDE1MTkwMTQwNiwiYXNzZXRfYWdlX2RheXMiOjEsInZpX3VzZWNhc2VfaWQiOjEwNzk5LCJkdXJhdGlvbl9zIjoxNSwidXJsZ2VuX3NvdXJjZSI6Ind3dyJ9&ccb=17-1&_nc_gid=AAKPvVbhpicU1KWnu0QBTg&_nc_ss=7e289&_nc_zt=28&oh=00_AQP664UN1r7iP0kJyVYrqRE24ZoosSVjIOtKczAjZIE3RA&oe=6ACDC91A

… 82 more ads

Crawled 2026-09-23. Token counts per ad for this crawl; image and video links are most of the difference. Full shapes in the API reference, generated from the schema.

The seven tools

ToolWhat it doesCost
find_advertiserTurns a brand name or domain into candidate pages. Your agent asks you which one.free
get_advertiser_adsEvery ad one or more pages run, newest first, with EU data.per ad
get_keyword_adsAds matching a keyword, across advertisers, with every advertiser listed.per ad
get_jobWaits for a job and reads its result, again and again for 90 days.free
cancel_jobStops a job and keeps what it fetched.free
refresh_adsCurrent status of ads you already have. Pro.per ad
get_accountCredit, plan, limits and recent jobs.free

Next steps

Set up your agent

Any agent: paste this

Set up AdSentinel so you can get Meta Ad Library ads for me.

1. Read https://adsentinel.eu/docs/quickstart.md
2. Run `npx adsentinel login` and show me the link it prints.
   I'll approve it in my browser.
3. Add the MCP server `npx -y adsentinel mcp` to your config,
   or use the `adsentinel` CLI if you have a shell.
4. Test it for free: look up the advertiser "Zalando" in Spain
   and show me the candidates. Don't fetch any ads yet.

Claude Code: install the plugin

/plugin marketplace add adsentinel-eu/adsentinel
/plugin install adsentinel@adsentinel

Paste the prompt into an agent that runs in a terminal, such as Claude Code, Codex, Hermes or Gemini CLI, not into a chat window: the agent has to run `npx adsentinel login`. Either way, you approve the sign-in once in your browser. It's the one step an agent can't do for you. New accounts get €2 of free credit.