Documentation version: 2026-11-16.2
Canonical: https://docs.creator.gg/guides/ads-reporting.md

# Meta product-acquisition reporting

Use this subset to review existing paid product-acquisition campaigns: which account/campaign/creative is running, reported spend and clicks, and the available native campaign statistics. It does not create demand, change delivery, install tracking or measure product activation automatically. API availability is not a reason to run a campaign or to include local-service lead capture in a startup growth plan.

## Access and discovery

Discover the actual tools, call workspace_status, then read the exact schema. These tools use the existing full workspace connection and the workspace module, not a new module, operator proxy or customer-selected workspace. Free preparation/intelligence access cannot execute these connected reads. The connection supplies the workspace and server-held account token. Requested optional ad permissions do not prove a current grant or an enabled Meta integration. ADS_ACCESS_UNAVAILABLE is not an empty report: retain the existing connection and ask Creator Labs support to review access. Do not reconnect, change scopes or switch ad accounts to work around it.

1. ads_meta_integration_get returns credential-free existing connection state, currently connected ad account and safe linked-page summaries. It omits page tokens and raw settings. It cannot read two-way-sync configuration or enablement.
2. ads_meta_accounts_list lists only the workspace's already-connected account, not every account visible to the authorizing user. The documented account response has no continuation field; list completeness is not established. An empty partial result does not establish disconnection.
3. ads_meta_account_get reads that exact account's currency and timezone. Selecting another account is rejected.
4. ads_meta_entities_list reads campaigns, ad sets or ads using an explicit sourceType. INTEGRATION queries Meta; AD_MANAGER campaign discovery reads only locally published PAUSED/PUBLISHED campaigns, not drafts or every imported campaign. Do not relabel either branch as sync configuration or guaranteed import completeness.

For entity pages, follow the returned opaque next cursor with the same account, sourceType, entityType and parent IDs. No fetchAll is accepted. Each response is capped at 1,000 entities without silent truncation. Ad sets require the Meta parent campaignId. Ads require that campaignId and optionally its verified Meta adSetId. Parent discovery is bounded to five pages; ADS_PARENT_NOT_VERIFIED means verification was not established, not that the campaign is absent. Entity status is provider-specific: campaign configured/effective status, ad set effective status (which may inherit a paused campaign), and ad configured status are different. AD_MANAGER campaign statuses are local publishing states.

## Local campaign records are not Meta IDs

ads_meta_campaign_get and ads_meta_campaign_report take campaignRecordId, the local 24-character Ad Manager record ID, not the Meta campaignId from entity discovery. The bounded published-campaign report list can return local _id values. Native campaign screens may supply them too. Do not guess, convert IDs or invent a source parameter. The campaign read verifies the workspace, connected ad account and linked child parents. It returns summaries only, omitting advanced configuration, creative bodies and raw metadata. editableStateComplete:false means it must not be copied into an upsert.

## Performance and measurement limits

ads_meta_report reads an account report with sourceType, explicit fields, optional day/week/month groupBy and two real YYYY-MM-DD dates. All report tools allow 1–31 inclusive days. To cover longer periods, request non-overlapping bounded windows and label each window; never sum unique reach across windows or invent a lifetime result.

- grouped and totals form the account envelope. Only requested metrics should be expected; absent cpc when there were no clicks is not zero. dataState distinguishes available, partial and empty retrieval, not complete business measurement. Missing fields remain missing.
- Native aggregate ratio totals such as cpm, ctr and frequency are summed, not weighted. They are not a recomputed portfolio CTR/frequency. cost_per_conversion and cost_per_result are placeholder zeros, not real zero acquisition costs. Use costPerConversion or the appropriate costPerResultBreakdown action when actually reported.
- Native conversions count Meta lead actions, not signups or activated product users. Meta results action types overlap: do not sum pageEngagement, postEngagement and linkClick. costPerResult may divide by that double-counted action total and is not cost per lead.
- ads_meta_campaign_report returns a flat campaign record/report, not grouped/totals. It requires a published local campaign with a Meta campaign ID. Meta results.lead and CDP leads (attributed contacts) are separate measurements and may disagree.
- ads_meta_campaigns_report_list uses the documented but deprecated v3 campaigns list, with a hard maximum of 25 records and no truncation. It excludes draft and archived campaigns. A row without insight dates is labelled not_reported_or_padded; its padded zeros are not confirmed zero performance. The provider recommends a newer reporting-rows API; this tool does not pretend to implement that different contract.
- Native CDP revenue/sales/leads and campaign results are not product activation, exact startup customer acquisition, cross-channel/global attribution or a new attribution model. Lower-level name-matching attribution can collide after renames or repeated creative names. Do not infer causal effects or automatically adjust budgets from these values.

Missing access, disconnected/expired Meta integration, mismatched owners, malformed reports, incomplete fields, empty responses and actual reported zeros are distinct outcomes. Bounded retrieval completion does not prove every campaign was imported, every conversion was attributed, or any paid change happened.

## Paid changes and two-way sync stay native

Use ads_native_handoff for a draft, edit, Publish, Pause, Resume, Budget, Delete, sync selection/refresh or connection review. This tool only returns instructions and a known workspace-root link. Its executed:false / HUMAN_ACTION_REQUIRED result is not a draft save, paid action, sync change or proof of completion. It makes no provider request.

The provider documents upserts and lifecycle APIs, but those upserts do not establish a safe atomic draft-only, version-preserving contract. Summary reads omit advanced state and cannot reconstruct a lossless replacement. There is no agent campaign-write tool in this subset. Native draft/edit is separate from explicit paid Publish/Resume/Budget decisions; Pause and Delete also need exact intent and scope. Review advanced settings, account, current state, budget, currency and schedule in Ad Manager before any authorized change. Setup or a reporting request never authorizes paid publication.

For existing Meta accounts, open Marketing > Ad Manager > Settings > Meta Account Settings to inspect two-way sync, campaign-status/time selection and background-import progress. Enabling or Refreshing sync is a distinct owner-authorized action, not a GET. Preserve current integration and connections. Do not replay attribution events, install pixels, configure number pools or apply source fixes to demonstrate reporting.

## TikTok is a precise native boundary

The reviewed public Ad Manager API index documents Meta and other networks but no TikTok Ads route. Organic TikTok social tools are not TikTok advertising APIs. The native launch describes lead-generation campaigns through Instant Forms/Direct Messages; this is not demonstrated product-signup/activation parity for a startup. Use the native Ad Manager TikTok screens only when the owner's actual request independently fits. Do not fabricate a TikTok ads tool, repurpose social publication, connect a new Business Center, change budgets or claim unsupported API parity.

## Recovery and receipts

These nine tools are read-only or non-executing handoffs. They create no operation receipt, paid mutation, campaign draft, customer record or attribution event. Repeated reads are not mutation replays. Existing mutation tools retain their stable requestId/body-free receipts and no-automatic-retry handling; this subset does not change that system. If a native paid action is already uncertain, inspect its existing receipt and protected native state with the original owner before any supported reconciliation. Never use a new request identity, blind retry or this handoff as proof that a native write failed or succeeded.
