> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Connect Meta business assets for advertising reports, campaign creation, and campaign management

## Connect your business

An organization admin connects Meta Ads from **Control Hub > Integrations**. Sign in to Meta, choose your business portfolio, and select the ad accounts and any Pages, Instagram accounts, catalogs, or pixels that agents should access. At least one ad account is required; the other asset types are optional.

The connection is shared within your Aster organization. Meta permissions and asset assignments determine what it can access. Use Aster's **Tools & permissions** settings and agent tool selection to control which agents can read or manage those assets.

The business login uses a system-user token. It can remain authorized without a scheduled expiry, but Meta or the business can still revoke access. If a token or data-access grant expires, reconnect from Control Hub. Aster keeps the token server-side and does not return it to an agent or the browser.

## Three tools

| Tool | Purpose |
| - | - |
| `meta_ads_query` | Discover accounts and read campaigns, ad sets, ads, creatives, audiences, Pages, catalogs, pixels, leads, and other accessible Graph resources. |
| `meta_ads_insights` | Run performance reports, select metrics and breakdowns, and submit or retrieve asynchronous reports. |
| `meta_ads_manage` | Create, update, copy, or delete advertising resources using Meta's native parameters. |

These tools accept native Meta fields and parameters, so features do not each require a separate tool. Meta validates which fields, permissions, and parameter combinations an endpoint supports.

The existing `search_meta_ads` tool remains available for public Ad Library research. Ad Library eligibility and verification are separate from business advertising access; connecting a business does not automatically grant Ad Library access.

### Account and campaign discovery

```json theme={null}
{
  "endpoint": "/me/adaccounts",
  "fields": ["id", "name", "currency", "timezone_name", "account_status"]
}
```

Then query `/act_<account_id>/campaigns`, `/adsets`, `/ads`, or another edge. Read an individual object with `/<object_id>`. Account paths use the `act_` prefix. Request useful fields explicitly; Meta's default selection can be minimal.

Use `/me/businesses` and a business's `/owned_ad_accounts` or `/client_ad_accounts` edges when exploring business relationships. Available results depend on the assets and permissions granted during connection.

### Performance reporting

```json theme={null}
{
  "action": "report",
  "object_id": "act_123456789",
  "level": "campaign",
  "fields": ["campaign_id", "campaign_name", "account_currency", "spend", "impressions", "clicks", "actions", "action_values"],
  "since": "2026-10-01",
  "until": "2026-10-07",
  "params": { "time_increment": 1 }
}
```

Dates are inclusive and interpreted in the ad account's timezone. Without a date selection, reports use `last_30d`. Use `params` for breakdowns, filtering, attribution windows, action report time, or unified attribution settings. Compare like-for-like definitions: different attribution settings, conversion action types, currencies, or timezones can change the meaning of totals.

For large reports:

1. Call `start_report` with the report definition and keep `report_run_id` from `content.result`.
2. Call `report_status` with that ID. Wait for `async_status` to be `Job Completed`; failed jobs are not empty reports.
3. Call `report_results` with the same ID and page through the rows.

### Creating and managing ads

```json theme={null}
{
  "endpoint": "/act_123456789/campaigns",
  "method": "POST",
  "params": {
    "name": "Summer campaign",
    "objective": "OUTCOME_SALES",
    "special_ad_categories": [],
    "status": "PAUSED"
  }
}
```

POST to an object's ID to update its status, budget, targeting, or other supported fields. POST to a supported `/copies` edge to duplicate an object. DELETE removes an object or edge item. New campaigns, ad sets, and ads default to `PAUSED` when status is omitted; an explicit `ACTIVE` status can start delivery and spending.

Check the account's currency and the endpoint's budget-unit rules before writing. Insights spend and budget parameters are not interchangeable. API errors are returned to the agent, and writes are never automatically retried. If a request times out, query the resource before retrying because the write may already have succeeded.

Nested parameters such as `targeting`, `object_story_spec`, `asset_feed_spec`, and audience payloads are serialized for Meta. Image upload supports an API-compatible `bytes` payload; video creation can use `file_url`. A local file path or Aster attachment reference is not itself a Meta upload: obtain the supported media payload or URL first. Endpoint-specific multipart and resumable upload workflows are not automatically performed by these tools.

## Pagination and large results

Read tools retrieve one page at a time, with a default page size of 100 and maximum of 500. Meta may return fewer rows. When `has_more` is true, repeat the same request with `next_cursor` as `after_cursor`.

All three tools use Aster's shared `_spill` handling. Large fetched results become files with bounded inline previews. A file contains only the fetched page, not subsequent pages. Pagination metadata remains inline. If storage is unavailable, the response explicitly states that the complete result is unavailable. Direct API calls retain their direct-response size limit.

## Troubleshooting

### Pilot testing while Meta review is pending

The unpublished app is not yet a public customer connection. Before a pilot tester connects, an Aster app administrator must add their real Facebook account under **App roles > Roles > Add People > Tester**, and the tester must accept the invitation. Meta requires a Facebook Developer Account for this role. The Tester role allows testing permissions without granting app-settings administration. Meta may still restrict particular assets or features until the required reviews are complete.

For the tester:

1. Sign in to Aster on `www.asteragents.com` as an admin of the organization that should own the connection.
2. Open **Control Hub > Integrations > Meta Ads**, continue to Meta, and sign in with the Facebook account invited as an app tester. To test the business integration system-user flow, that account must have full control of the client business, which must be separate from Aster's app-owning portfolio, and access to the assets being selected.
3. Choose the business portfolio and intended ad account. Select any Pages, Instagram accounts, catalogs, and pixels needed for the test, then finish the authorization and return to Aster.
4. Enable **Query Meta Ads** and **Meta Ads Insights** on a test agent. Ask it to list accessible accounts, then report campaign spend, impressions, and clicks for a short, explicit date range on the chosen account. Compare with Ads Manager using the same timezone, attribution settings, and date range.
5. For an explicitly authorized write test, also enable **Manage Meta Ads** and request a clearly named, paused test campaign. Keep it paused and confirm the returned ID and status in Ads Manager. Activation and spending are separate actions.

If login or a tool fails, share the exact error, step, and time with Aster. Do not send access tokens or app secrets. A successful invitation or connection alone does not establish that every permission or asset is accessible.

* **Missing asset:** Confirm that the connecting business has access and selected the asset during login. Reconnect to grant additional assets.
* **Permission error:** Confirm the permission's access level in the Aster Meta app and the connected business's role on the asset. Page advertising, lead retrieval, catalogs, and partnership ads use additional permissions.
* **Expired or revoked connection:** Reconnect Meta Ads in Control Hub. Tokens without scheduled expiry can still be revoked.
* **Report too large or slow:** Use the asynchronous report actions, a shorter date range, or fewer breakdowns.
* **Invalid reporting combination:** Reduce the selected metrics and breakdowns; not all combinations are valid in Meta.

## Disconnect and data deletion

Disconnecting in Control Hub removes this organization's stored Meta connection. To revoke the Meta-side grant, use Meta's business integration controls. Disconnecting does not erase previously generated conversation messages or report attachments; use Aster's deletion controls or [contact Aster](https://www.asteragents.com/contact) for assistance with retained data.

## Operator setup

This integration requires Aster's own Meta app, Facebook Login for Business configuration, and server environment variables:

* `META_APP_ID` — `1936571317326333` for the Aster app.
* `META_APP_SECRET` — server secret; never put it in a frontend variable or tool arguments.
* `META_LOGIN_CONFIG_ID` — `1111521144590653` for the **Aster Meta Ads** business login configuration.
* `OAUTH_STATE_SECRET` — shared OAuth-state signing secret already used by other integrations.

Register `https://www.asteragents.com/api/integrations/meta/callback` as a valid OAuth redirect URI. Keep HTTPS and strict redirect matching enabled. Development or preview hosts require their own exact registered callbacks; a production connection starts on `www.asteragents.com` so the browser-bound state cookie reaches the callback.

The callback validates the initiating organization admin, signed state and browser cookie, token app ID, system-user token type, expiry, and advertising permissions before saving a connection. Existing manually supplied tokens remain usable by the tools until replaced or disconnected.

For external customers, complete Business Verification, App Review for Advanced Access to the requested permissions, and the Marketing API Access Tier upgrade to Full Access before publishing. Meta [retired separate Access Verification on October 9, 2026](https://developers.facebook.com/blog/post/2026/10/09/retiring-access-verification-for-tech-provider-apps/); the Tech Provider classification still applies to this customer integration. A successful local build or saved login configuration does not establish external-customer access.

The configuration requests `ads_read`, `ads_management`, `business_management`, `catalog_management`, `instagram_basic`, `instagram_branded_content_ads_brand`, `leads_retrieval`, `pages_manage_ads`, `pages_read_engagement`, and `pages_show_list`. Asset selection and permission approval are separate: selecting an asset in business login does not grant an unapproved permission.

Meta also requires Advanced Access to `public_profile` for [Facebook Login for Business to serve external users](https://developers.facebook.com/documentation/facebook-login/facebook-login-for-business). This app-level login requirement does not mean adding `public_profile` to the system-user token configuration. The review form requires `pages_read_engagement` alongside `ads_management`, `pages_show_list` alongside Page permissions, and `instagram_basic` alongside `instagram_branded_content_ads_brand`.

[Marketing API Full Access](https://developers.facebook.com/documentation/ads-commerce/marketing-api/get-started/authorization) requires at least 500 successful Marketing API calls in the preceding 15 days and an error rate below 15% over the last 500 calls. Monitor these ongoing requirements. Permission tests are valid for 30 days and their counters can take 24 hours to update. The tier upgrade no longer requires a recording, but most of the individual permissions still require demonstrations.

Before rollout:

1. Complete Business Verification for the legal entity behind Aster's business portfolio. Add the Website platform with `https://www.asteragents.com/`, supply the app icon, and review published privacy and deletion disclosures for the Meta features being enabled. Complete the data-handling questionnaire using verified legal-entity, processor, and government-request information.
2. Configure the server variables above, deploy the integration, and run a real connection using an app-role account and its authorized test assets.
3. Verify account discovery, a bounded performance report, asynchronous report retrieval, creation of a paused test campaign, and disconnect/reconnect. Publishing ads or changing budgets requires the account owner's requested activation and spending intent.
4. Prepare permission-specific explanations and recordings showing Aster sign-in, Meta authorization, asset selection, and actual use of each requested capability. Supply a dedicated Aster reviewer account and reproducible instructions. Complete test-call requirements and submit App Review, including the Full Access tier request.
5. Confirm customer access with an account outside the app's roles after Meta approves the permissions and the app is published.

The local test suites are `scripts/test_meta_ads.mts` and `scripts/test_meta_oauth.mts`. They mock Meta requests and do not establish live permission access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.