Concepts

AdCrunch uses a small vocabulary, and it uses each word for one thing only. This page defines all of it. Read it once and the rest of the documentation reads without guesswork.

Several words in advertising mean two things. Where that happens, the entry says which one AdCrunch means, and what the other one is called here.

What you connect

Organization

What everything else belongs to. Your advertisers, your team, your billing, your API keys, and everything you write down are all scoped to one organization. You create it when you sign up, and its id starts with org_.

You can belong to more than one. Nothing crosses between them.

Provider

An ad platform AdCrunch connects to: meta, gads (Google Ads), tiktok, snapchat, dv360. You pass these exact strings to the API. Not every provider supports every capability — see what each provider supports.

Connection

One stored credential that links your organization to one account on one provider. You make a connection once, from Integrations in the console, and AdCrunch keeps using it. Reconnecting replaces the credential in place.

A connection is not an ad account. It is the permission to reach the ad accounts that account can see.

Advertiser

One ad account on a provider. Its id starts with acc_, and almost every read you make names one.

Each provider calls it something else: Meta says ad account, Google Ads says customer. AdCrunch says advertiser everywhere. Every ad account a connection exposes becomes an advertiser — you do not pick them.

What AdCrunch reads

Entity

Anything AdCrunch imported from a provider that is part of the account structure: a campaign, an ad group, an ad, a creative. An entity keeps the bare id its provider gave it, so an entity is identified by the three things together — provider, type, and id.

The type is the provider’s own word, not a normalized one:

Level	Meta	TikTok	Google Ads
Top container	campaign	campaign	campaign
Targeting and budget	adset	adgroup	ad_group
Unit of delivery	ad	ad	ad_group_ad

“Ad group” is the cross-provider name for the middle level in prose. It is not a value you pass. Google Ads Performance Max has no ad groups and no ads at all — it has an asset_group directly under the campaign.

Read entities with list_entities and get_entity.

Campaign

The top-level container for one advertising goal, on the provider. It is an entity, and it belongs to one advertiser.

Creative

The payload an ad delivers: the image or video, the headline, the body copy, the call to action, the link. It is a Meta concept — Meta stores a creative as its own account-level object, so one creative can be reused by many ads. TikTok has none: its creative material lives inside the ad.

A creative is not an Asset. A creative is the provider’s; an asset is yours.

Insight

One row of metrics — spend, impressions, clicks, reach, conversions — for one entity over one date interval. The provider’s reporting API produces it. AdCrunch does not compute it from entity state, and an insight has no id of its own: it is identified by its provider, entity, date, and interval.

A provider can revise a past date, most often conversions, which keep arriving after the click. AdCrunch re-reads a trailing window every day for that reason, so yesterday’s number can still move.

Read insights with query_insights.

Account currency and display currency

Every advertiser bills and reports in one currency, set by the provider. That is its account currency, and money reaches you in it by default, with a currency field beside it.

Ask for a display currency and AdCrunch converts instead — each row at the European Central Bank rate for that row’s own date, and then it adds the rows up. Nothing is converted at import, so changing the currency you ask for never needs a re-import.

If a row mixes two account currencies and you asked for no conversion, its currency reads null. That is the signal that the number is not comparable, not an error.

What you change

Mutation

One change AdCrunch makes on a connected ad account: create a campaign, an ad set, a creative or an ad; move a budget; pause, resume or archive.

A mutation is asynchronous. Starting one gives you a workflowId and nothing else; you poll it with get_mutation_status until it reads complete or errored. Every mutation lands on Activity in the console with the account, the change, who asked for it, and how it ended.

Two rules hold everywhere, and neither can be switched off:

• Nothing an agent creates starts spending. A create always arrives paused.
• The ad account is never caller input. It is derived from the advertiser you named, so there is no way to point a write at an account your organization does not own.

Writes work on Meta only today.

What you write down

These are the things your organization authors so that an agent understands what it is working on. They live in AdCrunch, and nothing here reaches a provider unless you execute it.

Skill

An ad-ops playbook your organization owns: instructions that teach an agent how to run a workflow using AdCrunch’s own tools. Write one in the console, and any connected agent can load it by name.

A skill is not a prompt or a template. Clients that support MCP prompts list your skills in a / menu, but that menu is a way of running a skill, not what a skill is.

Brand

What a brand is and what it intends, written as four optional markdown sections — identity, voice, guidelines, messaging. An agent reads it before it writes anything on that brand’s behalf.

A brand is free-form prose, not a record of typed fields. Each section is independently optional, and an unwritten one is normal.

Attach advertisers to a brand, and an agent working on one of those ad accounts can find out whose brand it is.

Persona

An audience archetype — who a brand talks to, described as a person. A persona belongs to exactly one brand and is reached through it, so two brands can each have a loyalists.

A persona is prose in four sections — profile, motivations, frictions, language — plus one typed field, an age range.

“Language” here means the words that audience uses for the problem, in their own register. It is not a locale.

Campaign Plan

Your statement of intent before you buy: what you mean to run, on which channels, for whom, for how much, over what period. It is checkable — it sums, it can be approved, and later you can compare it against what actually ran.

Approving a plan creates nothing and spends nothing. Turning one into live campaigns is a separate act that goes through a mutation.

A Campaign Plan is denominated in one currency, and every amount is an integer in minor units. It has two states, draft and approved.

AdCrunch never writes “campaign plan” as “campaign” or as “plan”. “Campaign” is the provider object; “plan” is a billing tier.

Line Item

One row of a Campaign Plan — one thing being bought. It is coarser than an ad set and deliberately not one-to-one with a campaign: a single line item may produce several provider objects, and the agent decides the shape.

A line item therefore carries only what stays true across everything it produces — a channel, a budget, a period, countries. It carries no optimization goal and no targeting script. It has two states, draft and validated, and validating it is what allows execution.

Channel

What a line item buys, in a planner’s words: meta, youtube, google_search, linkedin. A channel is not a provider. Four Google channels sit behind one connection, YouTube is buyable two ways, and you must be able to plan LinkedIn with no LinkedIn integration behind it.

Whether AdCrunch can execute a channel is derived at read time, not stored — so a plan does not become false when a new integration ships.

Asset

A source media file your organization owns — an image or a video — that AdCrunch stores. An asset exists before, and independently of, any ad that uses it. It always has bytes AdCrunch holds; a video hosted somewhere else is not an asset.

An asset belongs to your organization, not to an advertiser.

Registration

Placing an asset’s bytes into one advertiser’s provider-side library, and getting back that provider’s identifier for them. One asset can have many registrations — one per advertiser.

Registering does not put anything live. It makes the asset available for an ad to reference. AdCrunch never records a registration it did not perform itself.

Document

A file attached to something you defined — a logo, a brand-guidelines PDF, a positioning deck. An agent reads it, and it never leaves AdCrunch.

A document is not an asset. An asset is registered into a provider’s ad library; a document is reference material. They share an upload mechanism and nothing else.

Slug

The stable kebab-case handle an agent uses to fetch a skill, a brand, or a persona — skill_get(skill_name: 'weekly-report'). AdCrunch derives it from the name when you create the thing, and you can override it.

A slug is unique within what addresses it: within your organization for a skill or a brand, within its brand for a persona. Renaming one breaks callers of the old handle, so it is a deliberate act, not a side effect of editing the name.

How you reach all of this

MCP

The Model Context Protocol — the open standard an AI client uses to call tools on a remote server. AdCrunch hosts one at https://mcp.adcrunch.dev/mcp, and your client authorizes it once over OAuth. See what is MCP.

Scope

What an OAuth token is allowed to touch: insight:read, skill:write, campaign_plan:read, mutation:write, and the rest. Scopes are what stand between an agent and your ad accounts. Auth & scopes lists every one and says what it grants.

API key

A long-lived secret that starts with acr_, minted in the console, for calling the REST API from your own code. It belongs to the organization, not to you, and it keeps acting on the organization that was active when it was created. You see the secret once. See API keys.

What’s next

• The quickstart — the first ten minutes, using these words.
• What each provider supports — where each capability works.
• Auth & scopes — what an agent can and cannot change.