Quickstart · AdCrunch Docs

Key concepts

Five words carry the whole product. Concepts defines every other one.

An organization owns everything below. Its id starts with org_.
An advertiser is one ad account on one provider. Its id starts with acc_. Almost every call names one.
An entity is a campaign, an ad group or an ad that AdCrunch imported. It keeps the bare id its provider gave it.
An insight is one row of metrics for one entity on one date. AdCrunch adds them up over the range you ask for.
A mutation is one change AdCrunch makes on a live ad account. It runs asynchronously, and it leaves a record.

Ten minutes, start to finish

Create your organization
Sign up at console.adcrunch.dev with Google or an emailed code, then name your organization. The URL slug comes from the name and has to be unique, so you may need to adjust it. Billing, advertisers and team members are all scoped to it.
Connect an ad platform
Go to Integrations, press Connect, and pick a provider. The provider opens in a pop-up for you to sign in and grant access — if nothing appears, allow pop-ups for the console and try again. When you finish, the pop-up closes itself and the connection appears in the list. There is no page to reload.
Meta, TikTok and Google Ads can be connected today. What each provider supports says how deep each one goes.
Let the first import run
Every ad account the connection exposes becomes an advertiser — there is nothing to pick. AdCrunch then imports the last 90 days: your campaigns, ad groups and ads, plus a day at a time of insights for each of them. It runs in the background, so you can close the tab.
Expect minutes for a single ad account, and proportionally longer the more accounts the connection exposed.
Ask your first question
Three ways to read the same data. They return the same numbers because they read the same store.
Wire up your AI client once — Claude Desktop, Claude Code, Cursor or ChatGPT — then ask:

“What did each of my Meta campaigns spend last week, and what was the ROAS?”

Claude calls list_advertisers to find your ad account, then query_insights with a campaign breakdown, and reads the rows back to you.
Create an API key in the console, then:
```
curl -G https://insight.api.adcrunch.dev/insights \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -d select=spend,impressions,clicks \
  -d relative=last_7_days \
  -d breakdown=campaign
```
One row per campaign, as a JSON array:
```
[
  {
    "provider": "meta",
    "advertiserId": "acc_9f2c1b",
    "entityId": "120210000000000",
    "type": "campaign",
    "currency": "EUR",
    "spend": 4218.55,
    "impressions": 512038,
    "clicks": 7391
  }
]
```
Money comes back in the ad account’s own currency. Add -d currency=EUR to convert every row before AdCrunch adds them up.
Open Performance. Spend, impressions, clicks, CTR and conversions, filtered by provider and date range, with the breakdown beneath the chart.
Make your first change
AdCrunch also writes, on Meta: build a campaign or an ad set, move a daily or lifetime budget, and pause, resume or archive.
“Pause every Meta campaign under 1.5× ROAS last week.”

Claude reads the ROAS first, states the exact campaigns it means to pause, and then calls meta_set_status on each. Read what it says back before you agree — the same way you would with any agent holding your credentials.
```
curl -X POST https://mutation.api.adcrunch.dev/mutations \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "advertiserId": "acc_9f2c1b",
    "action": {
      "kind": "meta_set_status",
      "level": "campaign",
      "id": "120210000000000",
      "status": "PAUSED"
    }
  }'
```
The change is asynchronous, so you get a handle rather than a result:
```
{ "workflowId": "b3d1f0c4-6a2e-4a1f-9f77-2c0d1e5a8b94" }
```
Poll it until it stops running:
```
curl https://mutation.api.adcrunch.dev/mutations/$WORKFLOW_ID \
  -H "Authorization: Bearer $ADCRUNCH_API_KEY"
```
Open the Adgent and ask in plain language. It reads the same data and calls the same tools. Every change it makes lands on Activity, with the account, the change, who asked for it, and how it ended.
Warning
Two rules hold on every write
Nothing an agent creates starts spending — a create always arrives paused. And the ad account is derived from the advertiser you named, never from caller input, so a write cannot reach an account your organization does not own. Auth & scopes sets out the full boundary.

Note

The import has no progress indicator yet

Nothing in the console reports how far the import has got, so while it runs Performance says “No insight data for this period. Connect an integration or widen the date range.” — the same thing it says with nothing connected. Read that as the import still running, not as a failure. The connection itself is confirmed on Integrations the moment it succeeds, and the figures fill in behind it.

The console shows the same path. A First steps card sits at the bottom of the sidebar, and each of its four steps completes when you do that step — you do not mark it yourself. The card disappears when you finish the four, or when you dismiss it.

Your ad accounts, in one place your AI can reach.

Key concepts

Ten minutes, start to finish

What's next