meta/documentation/meta-ads.md

# Meta Marketing API

Proxy over the Meta Graph / Marketing API: reading the ad account structure
(ad accounts, campaigns, ad sets, ads, creatives) and insights (spend,
impressions, clicks, conversions).

**This phase is read-only.** Every endpoint issues a GET upstream; campaign
management is phase 2 (see `overview.md`, "Deliberately not wired").

Base URL: `https://graph.facebook.com/{version}` — the version comes from
`META_API_VERSION` (default `v25.0`) and can be overridden per request with
`X-Meta-Api-Version`, so a Graph upgrade needs no deploy.

## Credentials

| Header | Required | Meaning |
| --- | --- | --- |
| `X-Meta-Access-Token` | one of these | Access token → sent upstream as `Authorization: Bearer`. |
| `Authorization` | one of these | Standard `Authorization: Bearer <token>` — equivalent alternative (the X- header wins if both are sent). |
| `X-Meta-App-Secret` | no, recommended | App secret; the proxy derives `appsecret_proof` per request. |
| `X-Meta-Api-Version` | no | Graph version override, e.g. `v25.0`. |

> Use a **System User** token from Business Manager. Unlike a user OAuth token
> it does not stop working when someone leaves the company or changes their
> password, and when generated without an expiry it needs no refreshing at all.

Required permissions for this read-only phase: `ads_read`,
`business_management`.

## Endpoints

### Structure

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/ads/me/adaccounts` | Ad accounts the token can access. |
| GET | `/ads/me/businesses` | Business Manager accounts the token can access. |
| GET | `/ads/businesses/{business_id}/adaccounts` | Accounts owned by a business (`owned=false` → accounts shared with it). |
| GET | `/ads/accounts/{account_id}` | Ad account detail. |
| GET | `/ads/accounts/{account_id}/campaigns` | Campaigns in an account. |
| GET | `/ads/accounts/{account_id}/adsets` | Ad sets in an account. |
| GET | `/ads/accounts/{account_id}/ads` | Ads in an account. |
| GET | `/ads/accounts/{account_id}/adcreatives` | Creatives in an account. |
| GET | `/ads/campaigns/{campaign_id}` | Campaign detail. |
| GET | `/ads/campaigns/{campaign_id}/adsets` | Ad sets in a campaign. |
| GET | `/ads/campaigns/{campaign_id}/ads` | Ads in a campaign. |
| GET | `/ads/adsets/{adset_id}` | Ad set detail. |
| GET | `/ads/adsets/{adset_id}/ads` | Ads in an ad set. |
| GET | `/ads/ads/{ad_id}` | Ad detail. |
| GET | `/ads/adcreatives/{creative_id}` | Creative detail. |

`account_id` is accepted with or without the `act_` prefix.

Every list endpoint takes `fields` (comma-separated Graph fields, with a useful
default), `limit`, `after` (cursor) and `all_pages` (auto-paging, on by
default — see [Pagination](#pagination)). The account-level campaign
/ adset / ad endpoints also take `effective_status`, a JSON array such as
`["ACTIVE","PAUSED"]`.

### Insights

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/ads/insights/{object_id}` | Synchronous insights — small reports. |
| POST | `/ads/insights/{object_id}/jobs` | Start an async report job → `report_run_id`. |
| GET | `/ads/insights/jobs/{report_run_id}` | Job status (`async_status`, `async_percent_completion`). |
| GET | `/ads/insights/jobs/{report_run_id}/results` | Read a finished job. |
| POST | `/ads/insights/{object_id}/run` | Start, wait for completion, return the rows. |

`object_id` is an ad account (`act_123`), campaign, ad set or ad id.

Parameters (identical across all of them): `fields`, `level`, `date_preset`,
`time_range`, `time_increment`, `breakdowns`, `action_breakdowns`, `filtering`,
`sort`.

**Sync or async?** Meta computes large reports asynchronously and will reject or
time out a sync call that is too big. Rule of thumb: one account or a handful of
campaigns over a short period → `GET`. Long periods, several breakdowns, or a
whole account at ad level → `/run`.

`/run` polls until the job finishes or the wait budget
(`META_ASYNC_MAX_WAIT_SECONDS`, default 120 s, overridable per call with
`max_wait_seconds`) runs out. On timeout the job is **not** cancelled — the
response carries `completed: false` and the `report_run_id`, so you can keep
polling `/ads/insights/jobs/{report_run_id}` instead of losing the work.

#### Fields and levels

The default `fields` list is deliberately level-agnostic:

```
spend,impressions,clicks,ctr,cpc,cpm,reach,frequency,actions,action_values,date_start,date_stop
```

Name/id fields are level-specific — asking for `ad_id` at campaign level is an
upstream error. Add them together with `level`:

- `level=campaign` → `campaign_id,campaign_name,…`
- `level=adset` → `adset_id,adset_name,campaign_name,…`
- `level=ad` → `ad_id,ad_name,adset_name,campaign_name,…`

Conversions live in `actions` / `action_values` (arrays keyed by
`action_type`), not in a top-level metric.

### Generic read passthrough

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/graph/{graph_path}` | Any Graph API GET. |

For everything the typed endpoints do not cover (custom audiences, ad rules,
Instagram accounts, Pages…) without needing a deploy. GET-only by construction,
so the read-only stance holds here too. Give the path **without** the version
prefix — the version comes from config or `X-Meta-Api-Version`. Unknown query
params are forwarded verbatim.

## Pagination

The proxy **follows `paging.next` for you by default** (`all_pages=true`), so a
list call returns the complete list:

```json
{ "data": [ ... ], "pages_read": 3, "truncated": false }
```

`truncated: true` means the `META_MAX_PAGES` cap (default 100) was hit; the
response also carries the `next` URL and a warning is logged. Graph's own page
size defaults to 25 — pass a bigger `limit` (up to 500 on most edges) to fetch
more rows in fewer round trips.

Pass `all_pages=false` to get a single raw page with the upstream
`paging.cursors` untouched and drive the cursor yourself.

## Rate limits

`X-App-Usage`, `X-Ad-Account-Usage` and `X-Business-Use-Case-Usage` from the
upstream response are copied onto our response — use them to pace calls.

## Errors

| Status | Meaning |
| --- | --- |
| 401 `missing_credentials` | No token, or a malformed `X-Meta-Api-Version`. |
| 400 `upstream_error` | Meta rejected the request (bad field, bad id, missing permission). |
| 502 / 504 | Meta unreachable, 5xx, or a request timeout. |

Upstream errors keep Meta's status and the whole error object in
`upstream_body`, including `code`, `error_subcode` and `fbtrace_id` (quote it
when opening a case with Meta). `detail` prefers Meta's human-readable
`error_user_msg` when present.

Common ones:

- **code 100, "Invalid appsecret_proof"** — the app enforces app-secret proof;
  send `X-Meta-App-Secret`.
- **code 190** — token expired or revoked (a user OAuth token after a password
  change; a System User token generated with an expiry).
- **code 200** — the token lacks `ads_read` on that ad account.
- **code 17 / 613** — rate limited; check the usage headers and back off.

## Kde získat údaje (návod pro klienta)

- **Access token (System User)**: [Business Manager](https://business.facebook.com/)
  → *Nastavení firmy → Uživatelé → Systémoví uživatelé* → **Přidat** →
  **Přidat aktiva** (vyberte reklamní účty, oprávnění *Správa kampaní*) →
  **Vygenerovat nový token**. Bez zadané expirace je token trvalý.
  Oprávnění pro tuto fázi: `ads_read`, `business_management`.
- **App secret**: [developers.facebook.com](https://developers.facebook.com/apps/)
  → vaše aplikace → *Nastavení → Základní → App Secret*. Povinný, pokud má
  aplikace zapnuté *Require app secret proof for server API calls*.
- **ID reklamního účtu**: Business Manager → *Nastavení firmy → Reklamní účty*,
  nebo vlevo nahoře v Ads Manageru. Prefix `act_` je volitelný.

## curl examples

Campaigns in an account:

```bash
curl "https://services.csbot.cz/apps/meta/ads/accounts/123456789/campaigns?limit=200" \
  -H "X-Meta-Access-Token: EAAG..." \
  -H "X-Meta-App-Secret: <APP_SECRET>"
```

Daily campaign insights for June, run asynchronously:

```bash
curl -X POST "https://services.csbot.cz/apps/meta/ads/insights/act_123456789/run\
?level=campaign\
&fields=campaign_id,campaign_name,spend,impressions,clicks,ctr,actions\
&time_range=%7B%22since%22%3A%222026-06-01%22%2C%22until%22%3A%222026-06-30%22%7D\
&time_increment=1" \
  -H "X-Meta-Access-Token: EAAG..." \
  -H "X-Meta-App-Secret: <APP_SECRET>"
```

Anything not covered by a typed endpoint:

```bash
curl "https://services.csbot.cz/apps/meta/graph/act_123456789/customaudiences?fields=id,name,approximate_count" \
  -H "X-Meta-Access-Token: EAAG..."
```