# Quickstart

AdSentinel gets you the ads a brand runs on Facebook and Instagram, from Meta's public Ad Library, fetched live, with EU reach and audience. €3.99 per 1000 ads delivered. New accounts get €2 of free credit.

If you are an agent setting this up for a user, do the steps below in order. Step 1 needs your user once.

## 1. Sign in

    npx adsentinel login

It prints a link and a code, then returns. Show both to your user: they approve the code in their browser (about 20 seconds). Then run `npx adsentinel login` again: it waits up to a minute for the approval and stores the key in `~/.config/adsentinel/credentials.json`. `ADSENTINEL_API_KEY` overrides it.

## 2. Connect

Pick one. All call the same API with the same key.

- MCP client: add a server with command `npx`, args `["-y", "adsentinel", "mcp"]`.
- Claude Code: `/plugin marketplace add adsentinel-eu/adsentinel`, then `/plugin install adsentinel@adsentinel`.
- Shell: `npx adsentinel advertiser <name> --country XX`. In a non-interactive shell it prints the candidates and exits with code 3: ask your user, then pass the page id.
- HTTP: `Authorization: Bearer <key>`. Reference: https://adsentinel.eu/docs/tools.md

## 3. First call (free)

Call `find_advertiser` with `q: "Zalando"`, `country: "ES"`. Show your user the candidates and ask which page they mean. Do not call `get_advertiser_ads` until they answer.

## 4. Get ads

Call `get_advertiser_ads` with the chosen page id(s). Defaults: active ads, `maxAds: 500` (about €2), EU insights on. If the cost could pass the account's approval limit (€10 by default) you get `approval_required` and nothing is spent: ask your user.

## 5. Read the result

The first line is `next`: what to do or tell your user. Then a summary header, then the ads as CSV tables. Use `mode: "extra-compact"` for an overview and `get_job` in `full` for the ads that matter.

## Errors

Every error is `{ "error": { "code", "message", "next" } }`. Follow `next`.

AdSentinel is not affiliated with, endorsed by or sponsored by Meta Platforms, Inc.