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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Meta Ads campaigns and retrieve insights from Guild agents

> Connect Guild agents to Meta Ads to create campaigns, ad sets, and ads, update delivery status, and pull synchronous performance insights.

Integrations · Meta Ads

A Guild agent can create, update, and report on Meta Ads campaigns without a human opening Ads Manager. Guild stores the Meta Ads API key server-side so agent code never sees it, and credential policies let you restrict exactly which operations each agent may run.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Meta Ads.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Meta Ads to your first agent.

## What the Meta Ads integration exposes

The integration uses the Meta Marketing API v26.0. Tools cover ad accounts, campaigns, ad sets, ads, and performance insights. Agents can create campaigns (paused by default unless status is ACTIVE), create ad sets with billing event and optimization goal, create ads from an existing creative, update delivery and budgets with a sparse update, and retrieve synchronous stats at the account or object level. Tools are named with the `meta_ads_` prefix.

## How it works

**1. Connect your Meta Ads credential**

Go to Access & setup > Credentials, click Connect, select meta-ads, and paste your API key. Guild sends it as a bearer token in the Authorization header on every agent request.

**2. Scope the credential**

By default the credential serves every workspace the account owns. You can scope it to one workspace, one member, or one agent from the same Credentials page. See [Credentials](https://docs.guild.ai/platform/credentials.md) for the full scoping options.

**3. Add the tools to your agent**

Import MetaAdsTools from the integration package and spread it into your agent's tools object. Use [pick()](https://docs.guild.ai/sdk/tools.md) to include only the specific meta\_ads\_ tools your agent needs.

## Why Meta Ads access needs governing

Setting an ad object's status to ACTIVE resumes delivery and can spend budget immediately. Guild's credential proxy enforces [credential policies](https://docs.guild.ai/platform/credential-policies.md) before any request reaches Meta, so you can write DENY rules that block mutating operations like meta\_ads\_create\_campaign or meta\_ads\_update\_ad\_object for agents that only need to read insights. A DENY rule always takes precedence over an ALLOW rule, and agents cannot bypass the check because the credential is injected server-side only after the policy passes.

Credentials are stored and resolved by Guild, not by agent code. You can dedicate a credential to one agent, grant an existing credential to a specific agent, or restrict a workspace to its own credentials so shared account credentials never reach it. All of this is visible in the Credentials page, which shows each credential's scope alongside its connected integration.

## About the Meta Ads integration

Agents can create and update campaigns, ad sets, and ads across Meta ad accounts. They can retrieve account-level and object-level performance insights synchronously. Agents can also list and manage existing ad objects using the Meta Marketing API v26.0. The integration is `guildai~meta-ads`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Meta Ads**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **meta-ads**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { MetaAdsTools } from "@guildai-services/guildai~meta-ads"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Meta Ads.",
  tools: { ...MetaAdsTools },
})
```

### Selecting specific tools

Tools are named with the `meta_ads_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~meta-ads`:

| Tool | What it does |
| - | - |
| `meta_ads_create_ad` | creative.creative\_id must already exist. |
| `meta_ads_create_ad_set` | Requires campaign\_id, a billing\_event, an optimization\_goal, and targeting. |
| `meta_ads_create_campaign` | Creates a paused campaign unless status is ACTIVE. |
| `meta_ads_get_account_insights` | Synchronous stats. |
| `meta_ads_get_ad_account` | ad\_account\_id is the numeric id only. |
| `meta_ads_get_ad_object` | Graph node read. |
| `meta_ads_get_object_insights` | Synchronous stats for one object. level defaults from the object. fields and date\_preset match get\_account\_insights. |
| `meta_ads_list_ad_accounts` | Returns ad accounts the user or system user can access. |
| `meta_ads_list_ads` | Request fields id,name,adset\_id,campaign\_id,status,effective\_status,creative. |
| `meta_ads_list_ad_set_ads` | Ads whose parent is this ad set id. |
| `meta_ads_list_ad_sets` | Request fields id,name,campaign\_id,status,effective\_status,daily\_budget,lifetime\_budget,bid\_amount,billing\_event,optimization\_goal,start\_time,end\_time. |
| `meta_ads_list_campaign_ad_sets` | Ad sets whose parent is this campaign id. |
| `meta_ads_list_campaigns` | Request fields id,name,objective,status,effective\_status,daily\_budget,lifetime\_budget,budget\_remaining,bid\_strategy,special\_ad\_categories,start\_time,stop\_time. |
| `meta_ads_update_ad_object` | Sparse update. status ACTIVE resumes delivery and can spend. status PAUSED stops delivery. daily\_budget and lifetime\_budget are minor currency units as strings. bid\_amount applies to ad sets. |

## Frequently asked questions

> [accordion] Can an agent create an ad without an existing creative?
>
> No. The meta\_ads\_create\_ad tool requires that creative.creative\_id already exists before the call is made.

> [accordion] Does Guild support webhook events from Meta Ads?
>
> Not yet. The catalog entry for guildai\~meta-ads lists no webhook events, so agents cannot react to Meta-side events through Guild triggers.

> [accordion] How do I stop one agent from spending budget while letting another read reports?
>
> Write a DENY rule in [credential policies](https://docs.guild.ai/platform/credential-policies.md) that blocks meta\_ads\_update\_ad\_object and meta\_ads\_create\_campaign for the read-only agent, then scope an ALLOW rule to the reporting agent. The proxy enforces this before any request reaches Meta.

> [accordion] Can I use the same Meta Ads credential across multiple workspaces?
>
> Yes. An account-scoped credential serves every workspace the account owns by default. If a workspace has Use only credentials scoped to this workspace turned on in its settings, it will not use the shared account credential and needs its own.

## Put a governed agent on Meta Ads this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Meta Ads.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Meta Ads to your first agent.

## Related

**Also runs on Guild:** [Affinity](https://docs.guild.ai/integrations/affinity-openapi.md) · [Attio](https://docs.guild.ai/integrations/attio.md) · [Brex](https://docs.guild.ai/integrations/brex-openapi.md) · [Gong](https://docs.guild.ai/integrations/gong-openapi.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
