# Ads

> Facebook ad accounts, campaign performance, creating campaigns from Page posts, and lead form submissions.

Canonical: <https://www.tryadeli.com/docs/api/ads>

Facebook advertising, on the same connection as Pages. These are
platform-specific routes rather than a normalized surface: campaign structure
has no equivalent on the other providers Adeli covers.

Every endpoint needs a Facebook connection whose authorization includes the ads
permissions. A connection made before those were requested keeps working for
Pages and answers `403 ads_permission_required` here, with the missing scopes in
`error.details.missingScopes`; the fix is another authorization, not a repair.

> **Note:**
>
> Campaign and metric reads are live. Adeli stores no campaign structure and no
> metrics, so every figure is as fresh as that response. The one exception is the
> list of ad accounts, which is reused for up to 15 minutes.

When Meta throttles a request, the response is `429 rate_limited` with a
`Retry-After` header, `error.details.retryAfterSeconds` (Meta's own estimate
when it gives one, otherwise a minute) and `error.details.limit`: `app` when the
app's hourly call budget for this connection is spent, `ad_account` when that
ad account's own budget is.

When Meta refuses a request and explains why, the response is `422
provider_rejected` with Meta's explanation in `error.message` — for example
that a Business portfolio has reached its limit of ad accounts.

## Endpoints

- `GET /api/v1/ads/accounts` — [List ad accounts](https://www.tryadeli.com/docs/api/ads/list-ad-accounts.md)
- `POST /api/v1/ads/accounts` — [Create ad account](https://www.tryadeli.com/docs/api/ads/create-ad-account.md)
- `GET /api/v1/ads/businesses` — [List businesses](https://www.tryadeli.com/docs/api/ads/list-businesses.md)
- `GET /api/v1/ads/accounts/{adAccountId}` — [Get ad account](https://www.tryadeli.com/docs/api/ads/get-ad-account.md)
- `PATCH /api/v1/ads/accounts/{adAccountId}` — [Update ad account](https://www.tryadeli.com/docs/api/ads/update-ad-account.md)
- `GET /api/v1/ads/tree` — [Campaign tree](https://www.tryadeli.com/docs/api/ads/get-campaign-tree.md)
- `GET /api/v1/ads/insights` — [Daily insights](https://www.tryadeli.com/docs/api/ads/get-insights.md)
- `POST /api/v1/ads/campaigns` — [Create campaign](https://www.tryadeli.com/docs/api/ads/create-campaign.md)
- `DELETE /api/v1/ads/campaigns/{campaignId}` — [Delete campaign](https://www.tryadeli.com/docs/api/ads/delete-campaign.md)
- `PUT /api/v1/ads/status` — [Update ad status](https://www.tryadeli.com/docs/api/ads/update-status.md)
- `GET /api/v1/ads/leads` — [Lead forms and leads](https://www.tryadeli.com/docs/api/ads/list-leads.md)