Meta Marketing API: Complete Guide 2026

TL;DR: The Meta Marketing API gives you programmatic access to your ad accounts — campaigns, ad sets, ads, and performance data — without touching Ads Manager. This guide covers every layer: app setup, authentication, access tiers, core endpoints, rate limits, versioning, and error handling. If you need that same intelligence layer across TikTok, YouTube, LinkedIn, and Meta in one API call, that is a different problem that requires a different tool.

The Meta Marketing API is one of the most useful APIs in digital marketing. It is also one of the most poorly documented in practice — Meta's official reference covers endpoints and parameters but skips the operational realities: token expiry edge cases, rate-limit behavior at scale, version deprecation timelines, and the difference between what Standard and Advanced access actually let you do.

This meta marketing api guide is for practitioners: developers building internal tools, media buyers automating reporting, growth engineers setting up programmatic campaign management. It covers everything from Meta Marketing API app creation to production-grade error handling, with concrete examples at each step.

What the Meta Marketing API Actually Covers

Before setup, it helps to be precise about what "Meta Marketing API" refers to. The term is used loosely across documentation and blog posts, often conflating three related but distinct APIs.

The Marketing API (this guide's focus) gives you access to ad account data: campaigns, ad sets, ads, audiences, budgets, bids, and performance insights. If you are creating, editing, or reading data about ads that you run, this is the API you need.

The Ad Library API gives you access to Meta's public ad transparency database. It returns creative content, run dates, and estimated reach for any advertiser's transparency-visible ads — not performance metrics. It has its own separate authentication flow and its own separate rate limits. See the guide to competitor ad research for how to use it operationally.

The Graph API is the underlying infrastructure both above APIs run on. Most Marketing API calls are Graph API calls with ad-specific resource paths. Understanding this matters when you're debugging: error codes from the Graph API layer are different from error codes from the Marketing API validation layer.

For this guide, "Meta Marketing API" means the first: programmatic access to your own ad accounts via the Meta developer platform.

Setting Up Your Meta App

Everything starts with a Meta app. The app is the authentication container — it holds your API credentials, permission scopes, and access tier.

Step 1: Create the app

Go to developers.facebook.com and click "Create App." Select the "Business" app type — this is the only type that supports the Marketing API product. Give the app a name and associate it with your Business Manager account.

Step 2: Add the Marketing API product

Inside the app dashboard, navigate to "Add Product" and select "Marketing API." This adds the relevant permission scopes to your app's configuration and enables the token exchange endpoints you'll need.

Step 3: Connect your Business Manager

In Settings → Advanced, link the app to the Business Manager that owns the ad accounts you'll be accessing. Without this link, your tokens won't have access to the ad account data even if the permission scopes look correct.

Step 4: Understand your access tier

At creation, your app has Standard access to the Marketing API. This is sufficient for accessing ad accounts you own or have admin access to. If you need to act on behalf of third-party advertisers (i.e., you're building an agency tool or a SaaS product), you'll eventually need Advanced access via App Review.

For most internal tools and personal automation workflows, Standard access is all you need. Don't apply for Advanced access until you've confirmed Standard doesn't cover your use case — the review process is time-consuming.

Authentication: Tokens, Scopes, and Expiry

Meta Marketing API authentication is where most practitioners hit problems first. Meta uses OAuth 2.0 with a token system that has non-obvious expiry behavior.

Token types

Meta issues three kinds of tokens relevant to Marketing API work:

• Short-lived user token: Generated when a user authorizes your app via OAuth. Expires in about 1-2 hours. Not useful for automated workflows.
• Long-lived user token: Exchange the short-lived token for a 60-day version using the /oauth/access_token endpoint with your app secret. This is your primary token for scripts and scheduled jobs.
• System user token: Created in Business Manager under System Users. Does not expire unless you manually revoke it. Best practice for production automation — no 60-day renewal cycle.

For any Meta Marketing API workflow that runs on a schedule (nightly reporting pull, weekly competitive analysis, automated bid adjustments), use a system user token. The ad intelligence for AI agents use case covers how to set this up for agentic workflows.

Required permission scopes

For most Marketing API workflows you need:

• ads_read — read campaigns, ad sets, ads, insights
• ads_management — create and edit campaigns, ad sets, ads
• business_management — access Business Manager resources
• read_insights — pull performance data via the Insights endpoint

You don't need all four for every workflow. A read-only reporting tool only needs ads_read and read_insights. Requesting fewer permissions reduces your attack surface and makes App Review easier if you eventually need it.

Token security

Never embed Meta Marketing API tokens in client-side code or public repositories. Store them in environment variables or a secrets manager. A leaked system user token with ads_management scope can create and spend on campaigns — that is a real financial risk, not a theoretical one.

Core Endpoints: What You'll Actually Use

The Marketing API has hundreds of endpoints, but most practitioners use about eight on a regular basis. Here are the high-value ones with their practical use cases.

/act_{ad-account-id}/campaigns

List all campaigns in an account, or create new ones. Key fields: name, status, objective, daily_budget, lifetime_budget, bid_strategy. This is typically your entry point for any campaign management workflow. See automated Facebook ad launching for how this integrates into a programmatic launch pipeline.

/act_{ad-account-id}/adsets

List or create ad sets. Key fields: name, targeting, bid_amount, daily_budget, optimization_goal, billing_event, start_time, end_time. The targeting field is a complex JSON object — its structure is documented in Meta's Targeting Search API reference.

/act_{ad-account-id}/ads

List or create individual ads. Key fields: name, adset_id, creative, status. The creative field either references an existing ad_creative_id or contains an inline creative spec. Inline creative specs are convenient for testing but harder to reuse — build your creative library using the /adcreatives endpoint instead.

/act_{ad-account-id}/insights

Performance data. This is the endpoint you'll hit most for reporting. Key parameters: date_preset or time_range, level (campaign/adset/ad), fields (impressions, clicks, spend, conversions, cpc, cpm, ctr, roas). The breakdowns parameter splits results by age, gender, placement, device, or region — essential for audience segmentation analysis.

/act_{ad-account-id}/audiences

Create and manage custom audiences. Supports lookalike audiences, customer list uploads (hashed), website retargeting via pixel, and engagement-based audiences. The audience creation flow is asynchronous — create the audience, then poll its status before referencing it in ad sets.

/adcreatives

Store and manage ad creative assets independent of specific ads. A well-structured creative library with properly named adcreatives lets you reference the same creative across multiple ad sets without duplication. Critical for creative testing workflows where the same creative runs against different audiences.

/me/adaccounts

List all ad accounts the current token has access to. The first call you make in any new integration to verify authentication is working and to discover which account IDs you can operate on.

Rate Limits: The Spend-Tier Model

The Meta Marketing API rate limits are spend-based — accounts with higher monthly ad spend get higher call quotas. This is documented in Meta's rate limiting guide but the operational implications are worth spelling out.

Every API response includes the X-Business-Use-Case-Usage header. This JSON object tells you your current consumption percentage for the relevant rate-limit bucket. A value above 80% means you should slow down; at 100% you'll receive error code 17 (User request limit reached).

Rate limits reset on a rolling basis, not at a fixed clock hour. Watch the header.

Practical rate limit strategies:

• Batch requests: The Graph API supports batch requests — up to 50 calls in a single HTTP request. One HTTP request counts as one rate-limit unit regardless of how many sub-requests it contains.
• Async insights: Large insights queries should use the Async Job endpoint rather than synchronous calls. Async jobs run in the background and don't consume rate-limit quota during execution.
• Exponential backoff: When you hit error code 17, wait and retry with exponential backoff (start at 60 seconds, double on each failure, cap at 16 minutes).
• Field selection: Only request the fields you need. Sparse field selection reduces response size and processing time on Meta's side.

For high-volume workflows at agency scale, the ad spend estimator can help model whether your projected API call volume fits within Standard access limits.

Versioning and Deprecation

Meta versions the Meta Marketing API by date (e.g., v20.0, v21.0). New versions release roughly every 6 months. Old versions deprecate 2 years after release.

Breaking changes within a version: Meta sometimes introduces behavioral changes without a version bump. Subscribe to the Meta for Developers changelog and audit your integrations after each update.

Default version behavior: Calls without an explicit version route to the "default" — not always the latest. Specify the version in every call.

Migration strategy: Run your full test suite against a new version in staging before the old version deprecates. Meta publishes a migration guide per version; read "breaking changes" first.

For teams that need to stay ahead of Meta platform changes for competitive intelligence purposes, AdLibrary's ad timeline analysis surfaces when competitors adjust their creative cadence, which often correlates with platform changes.

Error Handling: The Codes That Matter

Meta Marketing API error codes divide into two layers: Graph API errors (authentication, rate limits, infrastructure) and Marketing API errors (validation, business logic).

Graph API errors you'll encounter regularly:

• Error 1 (Unknown): Graph API internal error. Retry with exponential backoff — usually transient.
• Error 2 (Service temporarily unavailable): Meta infrastructure issue. Same treatment as Error 1.
• Error 4 (Application request limit reached): App-level rate limit, different from the spend-based ad account limit.
• Error 17 (User request limit reached): Ad account rate limit hit. Back off and retry.
• Error 100 (Invalid parameter): Your request has a malformed parameter. Do not retry without fixing the request.
• Error 190 (Invalid OAuth token): Token expired or revoked. Refresh the token before retrying.

Marketing API errors:

• Error 294: Missing app access to the ad account. Verify Business Manager connections.
• Error 368: Account disabled or under review. Requires human intervention.
• Error 1487190: Creative validation failure. Check image dimensions and format requirements.

Building a robust error handler means categorizing errors into three buckets: retry (transient infrastructure errors), fix-and-retry (parameter or validation errors), and escalate (account-level issues requiring manual action).

For teams building production integrations, see api documentation and implementation guide for integration patterns that hold up under production load.

Pagination and Cursor-Based Navigation

Lists in the Marketing API return paginated results using cursor-based pagination. Every list response includes a paging object with cursors.before, cursors.after, and optionally next and previous links.

To paginate forward, append &after={cursor} to your next request. Do not use page numbers — the API does not support offset-based pagination on most endpoints.

Pagination pitfalls:

• The limit parameter: Default page size varies by endpoint (usually 25 for campaigns, 10 for insights). You can set it up to 100 on most endpoints.
• Cursor expiry: Cursors expire after a period of inactivity (usually 1 hour for most endpoints). Process pages promptly rather than fetching all cursors first and processing later.
• Change detection: If you're building an incremental sync, cursors do not work as change tokens. Use the updated_time field on campaigns and ad sets to filter for recently modified records.

The Meta Ad Library API: A Separate Tool

The Ad Library API provides public access to Meta's ad transparency database. You can query any advertiser's running ads by page ID, keyword, or country. The data returned is limited by design — Meta provides this for transparency compliance, not competitive intelligence.

Fields available include creative content (text, image/video URLs), funding entity, start date, and estimated reach ranges. Performance data, targeting, and spend are not available.

For operators running competitor ad research, the Ad Library API is a starting point, but its data coverage is shallow. You get the creative and rough dates — not performance signals, not enriched metadata, not cross-platform reach.

Meta's free API is fine for one platform. The moment you add TikTok, YouTube, or LinkedIn data into the same query, you need something else.

That is where AdLibrary's paid API sits. It is not a replacement for Meta's — Meta's API is free and adequate for basic transparency lookups. AdLibrary's is a paid power-user upgrade for three specific situations: you need richer metadata per ad (creative analysis fields, performance signals, enrichment), you need multi-platform data in one API call, or you need to avoid the app review and rate-limit management overhead of separate platform APIs. The Business plan at €329/mo includes API access. For teams building programmatic research workflows, see agentic marketing workflows with Claude Code.

Building Your First Reporting Workflow

The most common Meta Marketing API use case is automated reporting — pulling campaign and ad-level performance data on a schedule and pushing it into a dashboard, spreadsheet, or data warehouse.

Step 1: Authenticate with a system user token

Create a system user in Business Manager, assign it admin access to the relevant ad accounts, generate a non-expiring token with ads_read and read_insights scopes. Store the token in an environment variable.

Step 2: Enumerate ad accounts

Call GET /me/adaccounts?fields=id,name,currency,account_status to get the list of accounts. Cache this — it changes rarely.

Step 3: Pull insights

For each account, call GET /act_{id}/insights with your chosen fields, breakdowns, and date range. Use explicit time_range rather than date_preset — explicit dates produce reproducible results that are easier to backfill.

For large accounts, use the async insights endpoint: POST /act_{id}/insights. This returns a report job ID. Poll GET /{job-id} until async_status is Job Completed, then fetch the result via the report_run_id.

Step 4: Normalize and store

The insights response returns metrics as strings, not numbers. Parse all numeric fields before storing. Normalize currency values using the account's currency field — mixed-currency accounts are common in agency setups.

Step 5: Handle incremental updates

Meta allows historical data to be updated up to 28 days back as attribution windows close. Build a 28-day lookback window into your incremental sync. For attribution analysis purposes, pull the same date range multiple times over 28 days and keep the last value.

For the full campaign management automation pattern, see facebook ad automation platforms and facebook ads management guide 2026.

Campaign Management via API: Key Patterns

Beyond reporting, the Meta Marketing API supports the full campaign lifecycle — creation, editing, pausing, and deletion.

The creation hierarchy

Meta enforces a strict object hierarchy: Business Manager → Ad Account → Campaign → Ad Set → Ad → Ad Creative. You must create objects in this order — you cannot create an ad without an existing ad set.

For campaign structure planning, see meta campaign structure 2026 — covers how the Andromeda update changed optimal hierarchy depth.

Status management

Campaigns, ad sets, and ads each have independent status fields. Setting a campaign to PAUSED does not automatically pause its ad sets and ads — it only prevents delivery. The child objects retain their own status.

Best practice for Meta Marketing API status management: when pausing a campaign, also set all child ad sets and ads to PAUSED explicitly. When reactivating, set ads first, then ad sets, then the campaign.

Bid strategy interaction with budgets

Meta's Advantage+ bid strategies interact with the Marketing API in non-obvious ways. LOWEST_COST_WITHOUT_CAP requires no bid_amount field. LOWEST_COST_WITH_BID_CAP requires bid_amount. Sending a bid_amount field when LOWEST_COST_WITHOUT_CAP is selected does not fail — it silently ignores the value.

Creative reuse

Store creatives using POST /act_{id}/adcreatives and reference the creative_id when creating ads. This enables performance tracking at the creative level across all ad sets and campaigns — essential for ad creative analysis at scale.

AdLibrary's AI ad enrichment surfaces structured metadata (hook type, offer mechanism, social proof format) for competitor creatives — the same structured view you'd want on your own library.

Audience Management and the Targeting Spec

The Meta Marketing API targeting field in ad set creation encodes every targeting dimension: geotargeting, demographic targeting, interests, behaviors, and custom audience inclusions/exclusions.

A minimal targeting spec includes geo_locations, age_min, age_max, and optionally genders. Interest and behavior IDs must be looked up via the Targeting Search API (GET /search?type=adinterest&q={query}). They are not static — Meta periodically deprecates interest categories, so build a quarterly refresh into your workflow.

For audience segmentation strategy and how competitor targeting patterns inform your own, see precision audience targeting creative iteration and structuring competitor ad research workflow.

Lookalike audiences require a seed of at least 100 people; Meta recommends 1,000-50,000 for best quality. Lookalike creation is asynchronous — poll delivery_status before using it in an ad set.

Testing Before Production

For realistic Meta Marketing API testing without spending real budget: create a campaign in your own ad account with €1/day, set start date one week out, and run your full create/read/update/pause/delete workflow before it ever starts. Verify retry logic, pagination handling, and error parsing on real responses — not the test ad account system, which behaves differently.

For ad campaign planning pre-launch validation, the ad budget planner can help you model test campaign costs.

Always test rate-limit handling explicitly until you trigger error code 17 and confirm your backoff logic works.

When Meta's API Stops Being Enough

The Meta Marketing API does exactly what it says: it is Marketing API for Meta. That scope is both its strength and its ceiling.

Where practitioners hit the ceiling:

Multi-platform attribution. Your attribution model needs ad spend data from Meta, TikTok, Google, and LinkedIn in one schema. The Meta Marketing API gives you Meta's slice only. Building a unified multi-platform pipeline means maintaining separate integrations — separate auth, separate rate limits, separate versioning — for every platform.

Competitor creative intelligence at scale. The Meta Ad Library API is public but rate-limited with limited fields. For serious competitive research across 50 competitors and multiple platforms over 90 days, its coverage is insufficient.

App review friction. Advanced access to the Marketing API requires Meta's App Review process for apps that manage ads on behalf of third parties. The process takes weeks and requires detailed use-case documentation.

These are the three situations where AdLibrary's paid Meta Marketing API upgrade addresses genuine gaps: more data per ad (creative metadata, performance signals, enrichment), multi-platform coverage in one API call — Facebook, Instagram, TikTok, YouTube, LinkedIn, Snapchat, Pinterest, Google — and no app review required. The Business plan at €329/mo is the entry point; see api access feature for what's covered. The FTC's digital advertising guidance is relevant context for any team building commercial advertising tools. A 2024 HubSpot marketing report found structured competitor research consistently outperforms intuition-based campaign builds. For teams building with Claude Code or AI agents, claude code adlibrary api workflows shows concrete integration patterns.

For a broader view of where the Meta Marketing API sits in the programmatic ad ecosystem, the IAB's programmatic advertising framework provides useful definitional grounding.

Frequently Asked Questions

Is the Meta Marketing API free to use?

Yes, the Meta Marketing API is free. You pay for ad spend that runs through your connected ad accounts, but API access itself carries no per-call or subscription fee. Rate limits apply at the Standard access tier; Advanced access (for higher throughput) requires app review approval.

What is the difference between Standard and Advanced access in the Meta Marketing API?

Standard access is available immediately after creating a Meta app and adding the Marketing API product. It allows API calls to ad accounts you own or have admin access to, with rate limits based on spend tier. Advanced access enables broader permissions — such as managing ads on behalf of third-party advertisers — and requires formal App Review with Meta's compliance team.

How do Meta Marketing API rate limits work in 2026?

Meta uses a spend-based rate limit for the Marketing API. Each ad account gets an hourly call quota that scales with the account's monthly ad spend. The quota is communicated via the X-Business-Use-Case-Usage response header. When usage hits 80%, you should start throttling; at 100% you'll receive error code 17 and calls will fail until the window resets.

What data does the Meta Marketing API return that the Ad Library API does not?

The Marketing API returns performance data on your own ads: impressions, clicks, spend, conversions, ROAS, and audience breakdowns. The Ad Library API returns public transparency data on any advertiser: creative content, run dates, and estimated reach ranges. They are complementary, not interchangeable. The Marketing API tells you how your ads perform; the Ad Library API tells you what competitors are running.

When does it make sense to use AdLibrary's API instead of Meta's?

Meta's free API is the right tool for managing and reporting on your own Meta ad accounts. AdLibrary's paid API (available on the Business plan at €329/mo) makes sense when you need richer ad intelligence data across multiple platforms in one API call — Facebook, Instagram, TikTok, YouTube, LinkedIn, and more — without separate app reviews, rate-limit management for each platform, or sparse creative metadata. It is a paid upgrade, not a replacement.

The Bottom Line

The Meta Marketing API is the production-grade path for any Meta advertising workflow that outgrows Ads Manager. Authentication has friction upfront but is stable once configured. The core endpoints — campaigns, ad sets, ads, insights — cover the full campaign management lifecycle. Rate limits are spend-based and generous for most standard workflows.

The operational gaps Meta Marketing API practitioners hit are in scope, not capability. Meta's free API gives you excellent access to your own Meta campaigns. It gives you nothing on other platforms, and limited enriched data on competitors.

For workflows within that scope, this guide covers what you need. For scope gaps — multi-platform intelligence, richer competitor data, no app-review friction — AdLibrary's Business plan at €329/mo is the upgrade path.

For practitioners building on this Meta Marketing API foundation, meta ads strategy 2026 and facebook ads management guide 2026 cover the campaign strategy layer. Claude Code for competitor research automation covers automated intelligence workflows using AdLibrary's Meta Marketing API alongside Meta's own.