hyperfx-ai Snapchat Ads Campaigns
Strategic guide for managing Snapchat advertising via the Snapchat Marketing API v1. The toolkit is a raw-HTTP client, so parameter types must be sent exactly as documented — strings as strings, integers as integers, and all money in micro-currency.
Requirements
- Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
- Snapchat Ads integration connected (a Snap Business account with ad account access) at https://app.hyperfx.ai/apps.
If snapchat_ads_list_organizations is not in the tool list, stop and tell the user to enable Hyper MCP and connect Snapchat Ads. Creating ad squads or serving ads also requires an active funding source on the ad account — campaigns, media, and creatives can be created without one.
Out of scope — defer to other skills
- Creative generation (ad copy, images, video) →
ad-creative-generation/video-generation. - Cross-platform campaign launches → use this skill for Snapchat, then invoke
meta-ads/tiktok-adsseparately.
Critical Rules
CRITICAL: All budgets and bids are in micro-currency. $1.00 = 1,000,000 micros. $50/day =
50000000. Never pass dollar amounts directly. Minimum campaign daily budget / lifetime spend cap is $20 (20000000).
CRITICAL: Create campaigns, ad squads, and ads with
status="PAUSED". Never launch live without explicit user review. Because everything defaults to PAUSED, you can build a full campaign and delete it without spending — ideal for demos.
CRITICAL: Updates are JSON-Patch partial updates — pass only the fields you want to change, parented on the PARENT entity.
snapchat_ads_update_campaignneedsad_account_id;snapchat_ads_update_ad_squadneedscampaign_id(NOT ad_account_id);snapchat_ads_update_adneedsad_squad_id.
CRITICAL: Account-level stats (
entity_type="adaccounts") only supportfields="spend". For impressions / swipes / conversions, query at the campaign, adsquad, ad, creative, or media level.
CRITICAL: There is no
time_rangepreset (e.g.LAST_30_DAYSdoes not exist). Passstart_timeandend_time(ISO 8601). Omitting both returns lifetime totals, not a recent window.
CRITICAL: Ad squad
billing_eventis alwaysIMPRESSION.bid_microis required forbid_strategy="LOWEST_COST_WITH_MAX_BID"and"TARGET_COST"; omit it for"AUTO_BID".
IMPORTANT: Creating an ad squad requires an active funding source on the ad account. If the account is PENDING / unfunded, ad squad creation fails — that is a billing state, not a bug.
IMPORTANT: Creatives require
top_snap_media_id(an uploaded media id) and aheadline(≤ 34 chars).brand_nameis ≤ 32 chars.
IMPORTANT: For
LOWEST_COST_WITH_MAX_BID/TARGET_COST, don't guessbid_micro— get Snapchat's suggested range withsnapchat_ads_get_bid_estimate(by targeting spec before building, or by ad_squad_id after). Size the audience the same way withsnapchat_ads_get_audience_sizebefore creating anything.
IMPORTANT (customer lists):
snapchat_ads_add_segment_usersrequires identifiers that are already normalized and SHA-256 hashed (emails trimmed + lowercased before hashing; phones digits-with-country-code; mobile ad IDs lowercase with hyphens). One schema type per call (EMAIL_SHA256,PHONE_SHA256,MOBILE_AD_ID_SHA256), max 100,000 ids. Never send raw PII. Matching is asynchronous — segment size updates after processing.
Tool surface
| Group | Tools |
|---|---|
| Org & accounts | snapchat_ads_list_organizations, snapchat_ads_list_ad_accounts, snapchat_ads_get_ad_account |
| Campaigns | snapchat_ads_list_campaigns, snapchat_ads_get_campaign, snapchat_ads_create_campaign, snapchat_ads_update_campaign, snapchat_ads_delete_campaign |
| Ad squads | snapchat_ads_list_ad_squads, snapchat_ads_get_ad_squad, snapchat_ads_create_ad_squad, snapchat_ads_update_ad_squad, snapchat_ads_delete_ad_squad, snapchat_ads_estimate_ad_squad_outcomes |
| Ads | snapchat_ads_list_ads, snapchat_ads_get_ad, snapchat_ads_create_ad, snapchat_ads_update_ad, snapchat_ads_delete_ad |
| Creatives | snapchat_ads_list_creatives, snapchat_ads_get_creative, snapchat_ads_create_creative |
| Media | snapchat_ads_list_media, snapchat_ads_create_media, snapchat_ads_upload_media |
| Reporting | snapchat_ads_get_stats, snapchat_ads_create_stats_report, snapchat_ads_get_stats_report |
| Conversion | snapchat_ads_list_pixels, snapchat_ads_list_custom_conversions |
| Audiences | snapchat_ads_list_segments, snapchat_ads_get_segment, snapchat_ads_create_segment, snapchat_ads_update_segment, snapchat_ads_delete_segment, snapchat_ads_add_segment_users, snapchat_ads_remove_segment_users |
| Planning estimates | snapchat_ads_get_audience_size, snapchat_ads_get_bid_estimate, snapchat_ads_get_audience_insights |
| Targeting | snapchat_ads_search_targeting |
All reference files live in
references/. Read them atreferences/<file>(e.g.references/discovery.md).
Routing table
| The user wants to… | Read these files first |
|---|---|
| Launch a Snapchat campaign | references/discovery.md → references/campaign-creation.md |
| Upload media / create creatives / ad squads / ads | references/campaign-creation.md |
| Resolve targeting (geo, demo, interests, devices) | references/targeting.md |
| Build custom audiences / lookalikes / audience insights | references/targeting.md |
| Estimate audience size / get a suggested bid | references/campaign-creation.md |
| Set up Snap Pixel / custom conversions | references/conversions-and-reporting.md |
| Pull stats / async reports / update or delete entities | references/conversions-and-reporting.md |
| Goal not yet clear | references/discovery.md — discovery clarifies the goal |
Campaign Workflow
Discover org/account → audit account → research (objective, audience, budget, assets) → confirm strategy → create campaign (PAUSED) → upload media → create creative → create ad squad → create ad → review with user → activate (update_* to ACTIVE).
Known Limitations
| Issue | Workaround |
|---|---|
| Creative creation fails (historically a silent null error) | Almost always a missing profile_properties.profile_id (required for ALL creative types) — pull one from list_creatives. The tool now raises a clear error instead of a null "success". |
| Ad creation fails with a type mismatch | Omit type so it's derived from the creative (WEB_VIEW → REMOTE_WEBPAGE, etc.). |
| Forecast returns OE101 / UNSUPPORTED_DELIVERY_CONSTRAINT | The tool auto-adds delivery_constraint; if it persists, outcome estimation is unavailable for the account type (often PARTNER) — use the Ads Manager reach planner. |
| DAY-granularity stats reject the time range (E1008) | Handled automatically — pass ad_account_id to get_stats/create_stats_report and the tool aligns to account-timezone midnight + hour boundaries. |
| Media rejected with E2601 ("cannot be used to create any creative type") | The file doesn't meet specs — use a 1080×1920 (9:16) PNG/JPG ≤ 5 MB image or 1080×1920 MP4/MOV. Re-generate the asset at the right size, re-upload, and confirm media_status is READY. |
| Upload fails on file_path / internal URL (Errno 2 / DNS error) | Pass file_id (the Hyper file id) instead — it reads from storage directly. Avoid server-local paths and internal files.* URLs. |
Account-level stats reject non-spend fields (error E1008) |
Query other metrics at campaign/adsquad/ad/creative/media level. |
No time_range/date preset |
Pass start_time + end_time; omitting them returns lifetime totals. |
| Ad squad creation fails on unfunded accounts | Add a funding source; campaigns/media/creatives still work without one. |
bid_micro required for non-AUTO_BID strategies |
Provide bid_micro for LOWEST_COST_WITH_MAX_BID / TARGET_COST. |
| Media > 32 MB | Handled automatically (chunked upload, up to 1 GB). |
| Partial updates | Use the update tools (PATCH) with the correct parent id — never resend the whole object. |
| Customer-list upload "succeeds" but the segment stays small | Identifiers must be normalized + SHA-256 hashed before upload; matching is asynchronous and only hashes that match Snapchat users count. Check the segment's approximate_number_users after processing. |
| Lookalike creation rejected | Lookalikes need a healthy seed: a FIRST_PARTY segment with enough matched users, countries (ISO-2), and retention_in_days ≤ 180. |
Safety Rules
Never:
- Assume organization, ad account, campaign, media, or creative IDs — look them up or ask.
- Skip the account audit phase.
- Create campaigns, ad squads, or ads without explicit user approval.
- Set anything to
ACTIVEwithout user consent. - Pass dollar amounts instead of micro-currency.
- Query non-
spendmetrics at theadaccountslevel. - Use a
time_rangepreset — always passstart_time/end_time. - Use
LOWEST_COST_WITH_MAX_BID/TARGET_COSTwithoutbid_micro. - Pass the wrong parent id to update tools (ad squad →
campaign_id, ad →ad_squad_id).