Connect a Google Ads manager client
When issuing a connection link, set google_ads_manager_id to a directly accessible manager ID (10 digits, no dashes). Optional google_ads_customer_id restricts discovery to one enabled non-manager descendant. Omit both for direct accounts. Fresh Google consent is required. Techrace verifies the root and reads its native client hierarchy, including indirect clients, with a1000-candidate/2MB bound. An oversized or incomplete result fails; issue a new link for one known client. The customer selects one account, which becomes one normally billed connection. The manager/customer pair is encrypted with its credentials and retained during refresh; requests use that connection's login-customer-id. Changed selection requires a new link. This flow does not create or link native accounts, aggregate all clients, authorize spending or prove provider approval. Native permissions and current connection/financial guards still apply.
Implemented advertising reads
Use ads/query, SDK queryAds or MCP query_ads with ads:read. Meta Ads and Google Ads support account details plus campaign, ad_groups and ads lists. Daily insights support level account, campaign, ad_group or ad; Meta ad_group maps to an ad set. Google-only age_range/gender levels report separate daily ad-group criterion aggregates with preserved native labels, exact account/group/criterion/date identity and bounded pagination. Unknown and undetermined labels stay distinct; absent rows are not zero-filled. Separate age and gender reports do not describe individual people or a joint audience. Native campaign eligibility and privacy rules apply. Google-only keyword level reports configured positive Search keywords with account/group/criterion identity. It excludes negative and zero-impression criteria and is not a search-terms report or complete inventory. Keyword attributes are current native values. Reports preserve parent IDs, impressions, clicks and spend as strings in account currency. The optional performance metric set adds native Google conversion counts/values, view-through conversions, interactions and CTR, or Meta reach, frequency and action-type counts/values. Meta sends 7-day-click/1-day-view and impression-time parameters; these requested settings do not verify the effective attribution or reporting time. Optional include_attribution:true at Meta performance ad_group/ad level returns the native attribution_setting string or null. Treat it as untrusted native text, not proof of a historical/effective model or Ads Manager parity. Check metrics_basis; do not sum overlapping action types or compare different provider definitions. Google-only metric_set:search_share at explicit campaign level returns ten Search impression-share and budget/rank-loss estimates. Each value includes reported_ratio, interpretation and threshold_ratio:0.0999 means below10% share,0.9001 means above90% loss. Missing values are null. These estimated ratios cannot be summed or averaged to derive eligible impression counts or competitors; breakdown/attribution options are unavailable for this report. Advertising query ranges are at most 31 days. Real provider access, advertiser authorization and operator enablement are required.
Google campaign conversion outcomes
POST ads/google-campaign-conversions, SDK queryGoogleCampaignConversions or read-only MCP query_google_campaign_conversions. Select an exact campaign and1–31 advertiser-calendar days; optionally filter a native conversion_action reference. Daily action/category rows preserve fractional conversions, conversion value and all-conversions/value in advertiser currency. limit defaults100, maximum1000. Inspect metric_basis, truncated and complete_snapshot:false. Google can omit all-zero rows and update delayed data; no missing dates, costs, clicks or totals are invented. This bounded report has no continuation: narrow dates or select one action when truncated. Manager-owned action references remain references only. Current ads:read, native adwords, customer binding and final credential/authority checks apply. This does not create tracking, import conversions or authorize spending.
Pause or enable existing ads
POST ads/operations, SDK submitAdsOperation and opt-in MCP submit_ads_operation support set_status for an existing campaign, ad_group or ad. Specify entity_id, expected_status and desired status. Google ads also require ad_group_id. ads:write is required; enabling additionally needs ads:spend and spend_authorized:true because it can incur provider charges. Provider approval, actual native grants and separate operator write/spend switches must be enabled. Requests expire after 15 minutes and use an encrypted, idempotent queue.
Create paused Meta traffic campaigns and ad sets
Use ads/operations with create_campaign or create_ad_group, SDK submitAdsOperation, or MCP create_meta_campaign/create_meta_ad_group. Creation requires ads:write and actual ads_management, with separate operator enablement. Lifetime creation uses a total for the fixed schedule, not remaining or incremental spend; it explicitly requests standard pacing and disabled scheduling/dynamic creative. The receipt says native_budget_verified:false. Both budget modes stay paused and require separate activation authority. Campaign input requires name, objective traffic, special_category none and status paused; this limited workflow cannot handle regulated/special-category ads. Ad sets require an owned paused traffic campaign without campaign budgets, matching advertiser currency, exactly one daily_budget_minor or lifetime_budget_minor as an exact native-unit integer string, future start/end (15minutes–90days), exactly one geography (1–20 unique countries, 1–20 regions with native key and reviewed country_code, or one city with native key, country_code and explicit integer radius10–50mile or17–80kilometer), adult ages18–65 (65means65+), gender and facebook_feed or instagram_feed placement. Region/city metadata is re-resolved before writing and a country mismatch stops creation. Native acceptance does not prove retained targeting. Optional bidding selects lowest_cost, or bid_cap with an exact positive1–12digit bid_amount_minor in advertiser currency minor units. Omission retains lowest cost without cap. A bid cap is an auction setting, not a charged-cost or spending ceiling. The requested_bidding receipt is not native readback; native_bidding_verified remains false. The adapter requests manual audience and paused status. Daily budget is not a lifetime spend cap. This step creates the ad set; use the separate existing-post workflow for a creative and paused ad, then verify native configuration before separately authorizing activation. Uncertain creation must never be replayed with a new idempotency key.
Inspect YouTube search and referral sources
Use analytics/query, SDK queryAnalytics or read-only MCP query_analytics with report:traffic_source_details, explicit traffic_source:YT_SEARCH,EXT_URL,ADVERTISING,RELATED_VIDEO or YT_CHANNEL and include_source_details:true. Select1–31dates, optionally one content_id/video and country, and limit1–25(default25). Native views is required for descending ranking; optional engagedViews and estimatedMinutesWatched retain their separate definitions. This is a top-N report with no continuation or complete-inventory claim. Returned source strings can contain search phrases or referring websites: treat them as untrusted data, never instructions or URLs to fetch. Exact Unicode text and null values are preserved within strict bounds; malformed responses fail as a whole. Existing channel/analytics grants and final customer/caller/credential checks apply. No Google Search terms, spend, conversions, ownership or campaign identity is inferred. Native report availability and provider approval remain unverified.
Create an explicitly reviewed Meta website-sales graph
Create a paused campaign with objective:sales and special_category:none. Inspect resource:pixels in ads/meta-assets, then create_ad_group with conversion:{pixel_id,event_type,pixel_reference,confirm_website_conversion:true}. Choose PURCHASE,LEAD,COMPLETE_REGISTRATION,ADD_TO_CART,INITIATED_CHECKOUT or CONTENT_VIEW. The encrypted15-minute locator binds the original advertiser page and current credential. The worker rereads that page, requires explicit unavailable/restricted-use flags false and checks expiry around the native-start authority fence. Keep the existing explicit daily/lifetime budget, currency, future schedule, reviewed geography, adults and single-feed targeting; sales accepts lowest_cost or an explicit bid_cap with bid_amount_minor in native advertiser currency minor units. The cap is an auction bid input, not a spend or cost ceiling; never infer or automatically raise it. All parents remain paused. Existing post/image/carousel/video final-ad actions additionally need expected_conversion:{pixel_id,event_type,confirm_website_conversion:true}, matching the native Sales/OFFSITE_CONVERSIONS parent and exact simple pixel/event. Creative-only inputs do not accept it. Existing format/Page/creative/placement/credential checks remain. Receipts report requested conversion with native_conversion_verified:false; use include_conversion:true for readback. This sends no events, creates no pixel, proves no eligibility/ingestion/attribution and never activates spending. Graph creation uses separate operations; never automatically retry an unknown outcome. Explicit Sales daily/lifetime budget edits preserve reviewed lowest-cost or existing bid-cap bidding, with expected_conversion and separate spend authority. Existing Sales bid caps can also be edited after the same current conversion review; lifetime-budget bid edits additionally require exact expected_end_time while preserving budget/date; strategy changes remain outside that contract. New daily/lifetime Sales ad sets can explicitly select a bid cap while remaining paused; requested_bidding and native_bidding_verified:false require readback before separate activation. Native API compatibility and advertiser approval remain unverified.
Create an atomic paused Google Search campaign
Use ads/operations with create_google_search_campaign, SDK submitAdsOperation or opt-in MCP create_google_search_campaign. Ad text supports legacy unpinned strings or reviewed text/pinned_field objects; normalized text must be distinct and each headline/description position must have an eligible asset. Pinning constrains choices without guaranteeing rendering or delivery. This Google Ads v25 workflow creates one dedicated average daily budget, paused Search campaign, paused ad group and responsive search ad, plus explicit positive/negative keywords and location/language criteria in one atomic request. Require ads:write and actual adwords consent, matching advertiser currency/time_zone, positive integer daily_budget_micros plus manual cpc_bid_micros (default) or explicit bidding_strategy:target_impression_share with cpc_bid_ceiling_micros and impression_share containing native location ANYWHERE_ON_PAGE/TOP_OF_PAGE/ABSOLUTE_TOP_OF_PAGE plus integer-string location_fraction_micros1–1000000 (500000 means50%); this requests an auction objective without guaranteeing delivery or share. Other bid/conversion fields are refused in that mode. Or use explicit bidding_strategy:maximize_clicks with only cpc_bid_ceiling_micros, or maximize_conversions with the reviewed account-goal contract described above and optional target_cpa_micros, or maximize_conversion_value with the same fresh goal review, conversion_values_reviewed:true and optional numeric target_roas0.01–1000 (4.5 means450%). Value mode omits all CPC and CPA fields; review actual conversion-value measurement separately. Supply future start_date/end_date (1–90 inclusive days), eu_political_advertising none and status paused. Supply 1–20 location IDs, 1–10 language IDs, presence-only targeting, 1–20 keywords with explicit match types, 3–15 unique headlines and 2–4 unique descriptions, plus an HTTPS final URL. Native constants are rechecked. Search partners, Display, AI Max, text automation and URL expansion are disabled for the new campaign. Maximum normalized JSON is6500 UTF-8 bytes. A daily budget is an average, not a hard daily/lifetime cap. All three delivery controls remain paused and activation requires separate explicit spend authority. Native review and readback remain necessary. Inspect all returned IDs; ambiguous creation blocks further Search graph creation for that advertiser until investigated. Do not retry with a new key.
Edit a reviewed Search budget, manual bid or Maximize Clicks ceiling
Use ads/operations action update_google_search_impression_share to change an existing standard Search campaign’s reviewed location/fraction/CPC ceiling using complete expected_impression_share and impression_share objects, matching currency/status and spend_authorized true. Both ads:write and ads:spend are required including no-ops, reductions and paused campaigns. Native prechecks are not atomic and targets do not guarantee achieved share. No clearing, portfolio mutation or intentional strategy switch. Other ads/operations actions include update_google_search_budget, update_google_search_bid, update_google_search_click_ceiling update_google_search_target_cpa or update_google_search_target_roas, SDK submitAdsOperation, or the matching opt-in MCP tools. Both ads:write and ads:spend and spend_authorized true are required, including reductions and paused objects. Supply exact advertiser currency, expected campaign/group status, prior micro-unit amount and desired amount. Budget updates accept only enabled STANDARD/DAILY budgets with explicitly_shared false and exactly one campaign reference; bids accept only SEARCH_STANDARD groups under MANUAL_CPC Search campaigns. Maximize Clicks ceiling edits require a standard nonportfolio TARGET_SPEND Search campaign and expected_cpc_bid_ceiling_micros matching the existing positive ceiling, plus a positive new cpc_bid_ceiling_micros. Uncapped/portfolio strategies and ceiling removal are refused. CPA edits require a nonportfolio MAXIMIZE_CONVERSIONS Search campaign, exact expected_target_cpa_micros and positive new target_cpa_micros. Review goals and tracking separately; CPA is an average objective, not a cost cap. To add, explicitly use expected_target_cpa_micros null for a verified absent/default-zero target. To remove, supply a positive expected value, target_cpa_micros null and clear_target true. Portfolio edits and strategy changes are refused. ROAS updates require a standard nonportfolio MAXIMIZE_CONVERSION_VALUE Search campaign, conversion_values_reviewed true, matching expected_target_roas and positive target_roas JSON numbers from0.01 to1000. These are ratios:4.5 means450%. To add, explicitly use expected_target_roas null for a verified absent/default-zero target. To remove, supply a positive expected ratio, target_roas null and clear_target true. Zero and omitted inputs never mean removal. Removing a target changes the bidding objective while preserving strategy and budget. Review conversion goals and value measurement separately; values and returns are not verified or guaranteed. One field changes after current native identity/settings and final permission/credential checks. Status, bid strategy, keyword overrides and all other fields stay as they are. Average daily budgets are not hard daily caps. Outside edits can race native prechecks; the receipt does not prove final delivery or an atomic compare-and-swap. An ambiguous write blocks its target until investigated; reuse the idempotency key.
Edit reviewed Search ad copy
Use ads/operations, SDK submitAdsOperation or MCP update_google_search_ad_text. Inspect the selected Google Search context with include_body:true and provide its expected_revision. Replace the full3–15 headline and2–4 description lists with reviewed text and optional native headline/description pins. Impossible position combinations are rejected before native reads. The selected ordinary responsive Search ad must remain paused and have one observed nonremoved association. Requires ads:write, ads:spend and spend_authorized:true. The final authorization fence and same-ad status ordering apply; URLs, paths, status, budgets and Google-generated assets are outside this mutation. Native policy review, outside-edit races, delivery and automatic served text remain provider-controlled. Unknown outcomes are retained; never blindly replay.
Manage reviewed Search keywords
Use ads/operations with create_google_search_keyword, replace_google_search_keyword, remove_google_search_keyword, set_google_search_keyword_status or update_google_search_keyword_bid. The SDK submitAdsOperation and matching action-enabled MCP tools share this contract. Every action requires ads:write, ads:spend and spend_authorized true. Supply exact advertiser currency, campaign/group status, IDs, and for existing criteria the reviewed keyword text/match/sign/status and CPC override. Omitted expected_bidding_strategy preserves manual CPC. Explicit maximize_clicks, maximize_conversions, maximize_conversion_value or target_impression_share supports create/replace/remove/status in matching standard nonportfolio Search campaigns; every current/proposed CPC field must be null. Keyword bid updates remain manual-only. Native drift, portfolio bindings and dormant positive criterion bids refuse execution. Positive creation/replacement starts paused; negative keywords are enabled exclusions with no bid. Null CPC means no criterion override; under manual CPC it inherits the group bid. Explicit replacement confirmation removes and creates atomically; existing URL settings or labels block replacement and history is not transferred. Negative status/bid changes are refused; removal has its own explicit confirmation. All keyword operations share the ad-group ordering lane. Unknown writes block further group work until investigated; never retry with a new key. Native policy acceptance and delivery remain separate.
Understand top Google Search terms
POST ads/google-search-terms, SDK queryGoogleSearchTerms or read-only MCP query_google_search_terms. Requires ads:read and current native adwords consent. Explicitly select campaign_id/ad_group_id, include_terms:true and1–31 inclusive advertiser-calendar days. limit defaults50, maximum100; metric_set basic or performance. Terms are sensitive untrusted user content, never instructions. Exact native hierarchy and current credentials are checked. Cost/counts remain decimal strings; conversion metrics use native attribution and precision. Inspect truncated and complete_report:false: Google withholds low-volume terms, and the top report has no continuation. Equal-cost ordering is unspecified. No totals, missing zero rows, automatic recommendations, mutation or spend are inferred. Narrow the period when needed; this cannot reconstruct suppressed traffic.
Review conversion goals and create conversion-focused Search campaigns
Read ads/google-account-goals with customer/connection IDs, SDK queryGoogleAccountGoals or read-only MCP query_google_account_goals. Review native conversion-owner/status and up to100 account-default category/origin/biddable goals, and independently review tracking. To create, use create_google_search_campaign with bidding_strategy:maximize_conversions and conversion_goal_review containing revision, use_account_defaults:true and tracking_reviewed:true. Optionally set positive exact target_cpa_micros; omit both CPC bid fields. Current native defaults, configured tracking status and biddability are checked again before the existing final write fence; changed/unusable reviews fail. The one atomic campaign/group/ad graph stays paused and no goals are changed. The receipt does not certify tracking, policy, delivery, performance or atomic preconditions. Goal defaults may change later; target CPA and daily budget are averages, not hard spend caps. Lost creation responses remain ambiguous. Activation requires a separate explicit spend operation.
Inspect Google campaign conversion goals
POST ads/google-campaign-goals, SDK queryGoogleCampaignGoals or read-only MCP query_google_campaign_goals. Select exact customer, connection and campaign IDs with ads:read and current adwords consent. Inspect native conversion-customer/status, goal_config_level, category/origin/biddable goals and selected custom-goal action references. Up to100 goal rows and1000 custom references; inconsistent identities, duplicates, missing selected records and hidden continuation fail. Custom goals may make actions biddable regardless of primary_for_goal. The selected revision hashes independent reads; it is not a native version or atomic snapshot. tracking_verified:false means this does not test tags, action eligibility, conversion freshness or performance. No names, conversion events, manager traversal, mutations or spending are included. Current authority and credentials are checked again before disclosure.
Compare daily Google campaign device performance
POST ads/google-campaign-devices, SDK queryGoogleCampaignDevices or read-only MCP query_google_campaign_devices. Select an exact campaign under a customer connection and1–31 inclusive advertiser-calendar dates; optionally one native device code. Requires ads:read and current native adwords consent. Cost micros/currency decimals and click/impression counts remain exact strings, alongside native conversions/value/all-conversions/value. At most217 unique date/device rows; hidden continuation or malformed/duplicate rows fail. UNKNOWN, OTHER and UNSPECIFIED stay distinct. Missing dates/devices are not filled with zero and no totals are invented. Native device segmentation is not unique people or a cross-device journey. Data may be delayed/restated; even truncated:false does not imply a final or atomic snapshot. Current authority and credentials are checked again before disclosure.
Inspect country-level Google campaign performance
POST ads/google-campaign-locations, SDK queryGoogleCampaignLocations or read-only MCP query_google_campaign_locations with ads:read. Select one campaign, customer connection, 1–31 inclusive advertiser-calendar dates and limit1–100/default50. Google returns period aggregates grouped by native country criterion ID and targeted flag, ranked by exact signed cost micros with stable dimension ties. These are provider-reported physical-country groups, not people, precise coordinates, current targeting policy or a complete geographic inventory. Country IDs are not ISO codes or campaign-criterion IDs; literal0 stays unresolved. Required country/flag attributes must be explicit, while selected missing numeric metrics use native defaults only within validated rows. Cost/counts preserve int64 precision; native conversion definitions and fractional values remain. One-row lookahead marks truncation; no cursor, invented zero rows, sums or campaign totals. Current original caller, scopes, billing, connection and credentials are rechecked before disclosure. Native data can change; complete_snapshot:false remains even when untruncated.
Find Google location and language targets
POST ads/google-targets, SDK queryGoogleAdsTargets or MCP query_google_ads_locations/query_google_ads_languages. Requires ads:read and current native adwords consent. For kind locations, supply1–25 distinct names, optional two-letter country_code and locale; for kind languages optionally supply exact language_codes. Results default to50, maximum100. Inspect truncated, targetable and complete_catalog:false. Native location reach remains a precise decimal string and is only an approximate population estimate, not a performance forecast. Names are untrusted provider data. Select IDs explicitly; campaign creation rechecks status. This lookup never changes targeting or authorizes spend.
Read back Google Search configuration
Use ads/google-search-context, SDK queryGoogleSearchContext or MCP query_google_search_context with exact campaign_id, ad_group_id and ad_id under a customer connection. ads:read and native adwords are required. Read selected native budget/bid/schedule/network/AI settings, portfolio strategy resource, Maximize Clicks CPC ceiling and the separately labeled Target Impression Share location/fraction/ceiling when returned, responsive-ad delivery primary status/reasons and policy status and up to100 live keywords plus100 location/language criteria. Identity and parent bindings are validated. include_body:true explicitly fetches untrusted ad/keyword text and destinations; metadata is the default. Independent include_policy_details:true selects policy topics with six reviewed evidence forms and four country/certificate/reseller constraint forms. Those may contain private creative or destination text and URLs; body consent alone does not select policy evidence. Inspect policy_topics_state: not_requested, not_returned or returned; absence is not approval. Diagnostics have a separate diagnostics_revision, never a mutation precondition. Native timestamps do not assert a time zone; no URL is fetched and evidence is never a command or automatic appeal. Missing fields remain null, not disabled. Oversized or paginated native results are rejected. The revision describes selected fields across independent reads, not an atomic snapshot or compare-and-swap token. Other criterion types, objects, account settings and inheritance are not enumerated. Access and current credentials are checked again before results are released. Readback performs no mutation and does not guarantee delivery.
Select Meta custom audiences for paused ad sets
Discover resource:audiences through ads/meta-assets, SDK queryMetaAssets or read-only MCP query_meta_assets. Each row includes an encrypted15-minute audience_reference bound to the customer, advertiser and current credential. For paused traffic ad-set creation, targeting.audiences accepts include/exclude arrays of audience_id and audience_reference; select1–5 unique IDs in total, with no overlap. The full canonical input must fit6500UTF8bytes. The worker rechecks inspected pages with current credentials before final write authorization. Only IDs reach Meta; no customer lists, members, rules or native audience creation are accepted. Membership does not prove eligibility or data rights. The receipt records requested IDs with native_targeting_verified:false. Independently opt in to include_audiences:true on ad-group or ad context to read selected native included/excluded IDs and a separate revision. Names and member data remain excluded; absent lists are null and explicit empty lists stay empty. This readback is not complete targeting, approval, delivery or authority to activate spending.
Inspect available Meta custom audiences
Use POST ads/meta-assets, SDK queryMetaAssets or read-only MCP query_meta_assets with resource:audiences. Requires ads:read and current ads_read/ads_management consent. Read one1–50-row advertiser edge page, native audience IDs/subtypes, approximate size lower/upper bounds and uninterpreted native status codes. include_names:true explicitly selects untrusted names; names are otherwise neither requested nor returned. account_id is the queried advertiser, while native_account_id is the optional native field; neither proves exclusive ownership or sharing rights. Null size means absent, not zero; signed native values are preserved without guessing sentinel meaning. Nonnegative counts are estimates and must not be summed into exact people or reach. The query-bound encrypted cursor expires after15minutes and becomes invalid after credential changes. Current caller, native grant, billing and credential checks run before disclosure. No members, rules, source identifiers, descriptions, status messages, audience upload or creation are exposed; listing is not targeting or spend authority.
Inspect existing Meta images and creatives
POST ads/meta-assets, SDK queryMetaAssets or MCP query_meta_assets with customer_id, connection_id and resource images, creatives, creative or videos. Lists return25 items by default, maximum50; follow the opaque next_cursor using the identical query within15minutes. images optionally accepts image_hash; creative requires exact creative_id and has no pagination. Metadata is the default. include_body:true on exact creative inspection selects untrusted text and link-story content; other native formats and dynamic variations are not fully represented. Native advertiser ownership, actual permissions and current authorization/credentials are checked. With include_body:true, a present native video_data adds selected video/poster-hash/copy/CTA settings and unmodeled field paths without their values. This does not establish video ownership, readiness or ad eligibility. No native media URLs are returned or fetched. A selected-field revision is not a native atomic mutation precondition, a complete snapshot or proof that an asset is unused, approved, deliverable or safe to delete. Similar names are not sufficient evidence to reconcile uncertain creation.
Delete a reviewed Meta image or creative
Archive a known paused Meta campaign, ad set or ad with ads/operations, SDK submitAdsOperation or opt-in MCP archive_meta_entity. Select exact entity and parent IDs, expected_status:paused, confirm_archive:true and confirm_ads_may_be_affected:true. Current ownership and PAUSED status are rechecked; associated ads may be affected and descendants are not inventoried. The connection-wide cleanup barrier applies. Receipt means native acceptance only, never status readback, erasure or automatic graph rollback. For image/creative deletion: Use ads/operations, SDK submitAdsOperation or the opt-in MCP delete_meta_ad_image/delete_meta_ad_creative tool. Requires ads:write and current ads_management. Supply the exact image_hash or creative_id, a fresh metadata-only query_meta_assets expected_revision, confirm_delete:true and confirm_ads_may_be_affected:true. This can affect existing ads; asset usage is not enumerated. Techrace admits cleanup only after all unresolved ad work on this connection is resolved, and blocks new ad work until cleanup finishes or an owner explicitly acknowledges an ambiguous outcome. Other connections and native clients remain outside this barrier. Native acceptance does not prove physical erasure, revoke consent or delete private source files. Keep the same idempotency key and inspect the operation receipt; never automatically retry an unknown deletion or roll back a partial graph.
Upload an image and create a new paused Facebook ad
Upload a private same-customer verified JPEG/PNG (up to8MiB), then submit upload_meta_ad_image through ads/operations, SDK submitAdsOperation or MCP upload_meta_ad_image with media_id and expected_sha256. This requires ads:write plus media:write, pins the source against unresolved deletion and independently verifies its stored bytes before a native write. Use the returned native image_hash with create_image_creative (MCP create_meta_image_creative): explicit connected Page, HTTPS link, message/headline, optional description and learn_more CTA. The Page and advertiser require separate actual permissions and native promotion eligibility. create_image_ad (MCP create_meta_image_ad) rechecks exact creative content and compatible paused traffic parents before creating a PAUSED ad. Each step has a separate idempotency key and receipt. Nothing activates spend or automatically rolls back a partial graph. Native review, presentation and delivery remain unverified until staging; For image carousels, create_carousel_creative/create_carousel_ad and corresponding create_meta_carousel_* MCP tools accept 2–10 reviewed cards, preserve_card_order:true and a 6500 UTF8 byte configuration limit. Every hash is checked for native ownership; card order, links and copy are rechecked before a paused ad. Native optimization/end-card settings are explicitly false, without guaranteeing final presentation. Exact creative inspection with include_body returns selected ordered card fields. For Instagram feed, explicitly pass placement:instagram_feed and the reviewed Page-connected instagram_user_id. Images must be square and at least600px. Omit single-image headline/description and carousel-card descriptions; displayed card headlines stay required. The worker rechecks the same Page identity before its final write fence and requires exclusive Instagram stream placements on paused parents. Runtime51 carries this expanded contract. Video inventory is available with query_meta_assets resource:videos: one bounded advertiser edge page, selected native processing states/progress/error codes and an encrypted continuation cursor. Native phase failures remain status data; titles, error messages and media URLs are suppressed. Edge membership and a ready state do not prove exclusive ownership or advertising eligibility. Private ad-video asset upload is available separately through upload_meta_ad_video: same-customer verified MP4,16 bytes to20MiB, exact SHA256 and media:write plus ads:write. Its accepted ID does not prove processing; this action does not create a creative or ad. Reuse the operation idempotency key and investigate unknown outcomes. Facebook and Instagram feed video creatives and paused ads use create_video_creative/create_video_ad and corresponding create_meta_video_* MCP tools. Instagram requires placement:instagram_feed and the reviewed Page-connected instagram_user_id; submit message/caption and learn_more CTA, omitting headline/description. The identity is checked twice, and the final creative and exclusive Instagram stream parents must match. Facebook retains the following headline-based input. Pass the selected video_id and encrypted15-minute video_reference from library inspection, owned poster image_hash, Page connection, explicit placement:facebook_feed, HTTPS link, reviewed message/headline and learn_more CTA. The worker rereads the same bounded advertiser page and requires native ready status before the final authority fence. Missing/moved or reconnected selections require fresh inspection; the reference never grants write/spend authority. The full request including reference must fit6500UTF8bytes. Ad attachment rechecks exact native creative content and compatible paused parents. Native readiness is not policy approval or delivery; other placements and objectives remain separate.
Create a creative and paused ad from an owned Facebook post
POST ads/boost-context, SDK queryBoostContext or MCP query_meta_boost_context verifies a known published link post against both the advertiser and a separate Facebook Page connection for the same customer. The native post must have exactly one complete link attachment with an unshimmed HTTPS destination; multiple attachments, nested content and partial errors are refused. Review post_revision and link_url; message text is returned only with include_body:true. With ads:write, submit create_post_creative and then create_post_ad through ads/operations (MCP create_meta_post_creative/create_meta_post_ad). Both require expected_post_revision and expected_link_url. The creative may reuse an existing ID. The ad requires that creative, an owned paused traffic campaign and compatible paused adult Facebook-feed ad set with a future schedule. The advertiser must actually grant ads_management/pages_show_list/pages_manage_ads and the Page must grant pages_read_engagement. Reconnect either account and current credentials are checked again. These steps do not activate spending or prove native review approval. This existing-post flow does not cover Instagram, video, partner-post or special-category creatives; the separate image workflow supports verified private JPEG/PNG sources. Outside edits can race native prechecks.
Find and verify Meta geographic locations
Use ads/meta-locations, SDK queryMetaLocations or default read-only MCP search_meta_locations/resolve_meta_locations with ads:read. Search country, region or city names on one bounded1–50-result page; region/city queries can specify country_code. Resolve1–20 exact category-specific keys to native metadata, refusing missing or substituted locations. Native URLs and tokens are never returned. Current advertiser, caller, credential, permission and billing checks apply before disclosure. Results depend on provider access and can be non-exhaustive; flags do not prove targetability, reach, approval or delivery. This lookup does not create ads or broaden targeting; region/city creation support remains separate.
Provide Meta beneficiary and payer identities
When creating a paused ad set through ads/operations, SDK submitAdsOperation or MCP create_meta_ad_group, optional transparency contains beneficiary, payer and confirm_public_disclosure:true. Supply both truthful customer-authorized names, at most512characters each; Meta can display them publicly. Techrace sends them as dsa_beneficiary/dsa_payor, retains the reviewed request encrypted and omits names from the receipt. Omission preserves native account-default behavior and can fail where required identities are absent. Meta may discard the values for other destinations; acceptance does not prove retention or display. No names are guessed, no jurisdiction compliance is certified, and no spending is activated. Read selected native values with ads/meta-ad-group-context, SDK queryMetaAdGroupContext or MCP query_meta_ad_group_context and include_transparency:true. Omission suppresses names. Nullable observed identities have a separate transparency.revision; keep using the unchanged top-level revision for budget/bid edits. Final current authority and credential checks apply. Observed values do not prove public display. The transparency addition requires runtime52 or a compatible newer contract and approved native review before activation.
Inspect an Instagram advertising identity
POST ads/instagram-identity, SDK queryMetaInstagramIdentity or read-only MCP query_meta_instagram_identity takes customer_id, connection_id for the Meta advertiser and page_connection_id for the Facebook Page. Both must belong to the same customer and independently pass current permissions, billing and credential checks. The native Page must appear in the advertiser's promotion context. Returns the single Page-connected Marketing API instagram_user_id and untrusted username; it is not an Instagram Login connection or permission to read messages, publish or spend. Empty, multiple, incomplete or paged identities are refused. No additional connected-account record is created. The image/carousel workflow can use this explicitly reviewed identity and rechecks it before writing; this discovery read grants no approval and live compatibility remains unverified.
Break down Meta ad performance
Use ads/query, SDK queryAds or read-only MCP query_ads with resource insights, a1–31day since/until range and one optional fixed breakdown report: age, gender, country, publisher_platform, device_platform, age_gender or placement. age_gender requests age and gender together; placement requests publisher_platform and platform_position together. Meta-only; basic impression/click/spend metrics at account/campaign/ad_group/ad levels. Performance/action metrics, Google keyword/age_range/gender levels and arbitrary pairs are rejected. Every row preserves all requested native dimension labels; absent or suppressed buckets are not reconstructed as zero. The opaque cursor binds the chosen breakdown and current credentials. Native privacy rules, compatible report fields and permissions still apply. Deduplicate by advertiser, hierarchy, date and dimension across pages. The two paired reports are native aggregates. Separate marginal reports cannot be summed or joined into further audience distributions or individual people. Reports perform no targeting change or spend action.
Replace one Google Search location or language target
Submit replace_google_search_target through ads/operations, SDK submitAdsOperation or the action-enabled MCP tool. Review campaign_id, criterion_id, target_type, expected_target_id, target_id, currency, expected_campaign_status and expected_bidding_strategy; confirm_replace:true and spend_authorized:true are mandatory, with ads:write and ads:spend. Only positive enabled criteria on matching standard Search campaigns with no nondefault bid modifier qualify. Location edits preserve explicit PRESENCE mode. Current native identity/state and new constant availability are checked before one atomic remove/create. No-op requests still check current authority. Creation, spending and write gates apply. Criterion history is not transferred; external edits can race prechecks. The operation never activates a campaign or changes budgets/bids, and success does not prove delivery. Inspect unknown outcomes; never automatically repeat or roll back.
Add or remove a Google Search location exclusion
Submit create_google_search_location_exclusion or remove_google_search_location_exclusion through ads/operations, SDK submitAdsOperation or action-enabled MCP. Both require ads:write, ads:spend and spend_authorized:true, reviewed campaign/currency/status/standard strategy, and existing negative PRESENCE matching. Creation takes location_id and confirm_exclusion:true; removal takes exact criterion_id, expected_location_id and confirm_remove:true. Removing an exclusion can broaden reach. Creation resolves current targetability and requires the creation gate; removal binds the exact enabled negative criterion without requiring the location to remain targetable. One native request follows current authorization checks. The receipt states requested_state, native_accepted:true, configuration_verified:false and delivery_confirmed:false; it does not assert a unique new criterion or current absence. Prechecks can race external edits. Preserve idempotency and inspect uncertain outcomes without automatic replay or rollback.
Cancel a queued social inbox operation
Owner/admin clients can POST inbox/operations/{id}/cancel, call SDK cancelInboxOperation or action-enabled MCP cancel_inbox_operation with the exact stored expected_action and confirm_cancel:true. Both current inbox:operations:read and inbox:write scopes are required, including MCP consent. Only pending/leased work before current native start can be cancelled; started, ambiguous and other terminal outcomes conflict. Success clears queued input, emits one inbox.cancelled event and preserves idempotency, quota and historical Meta grants. Repeating cancellation reads the same receipt without resending. Source-media deletion pins and the target lane release. This does not unsend a reply, undo moderation, unread a conversation, remove an existing push subscription, delete assets, refund quota or prove delivery. It remains available while providers or native writes are paused.
Cancel a queued advertising operation
Owner/admin clients can POST ads/operations/{id}/cancel, call SDK cancelAdsOperation or action-enabled MCP cancel_ads_operation with the exact stored expected_action and confirm_cancel:true. All three current scopes ads:operations:read, ads:write and ads:spend are mandatory: cancelling a queued pause or budget reduction can leave existing spending unchanged. Only pending/leased work before current native start can be cancelled; started, ambiguous and other terminal outcomes conflict. Success clears queued input, emits one ads.cancelled event, preserves original idempotency/quota and historical Meta grants, and stops future attempts. Repeating the cancellation reads the same receipt under current access; it never resubmits native work. Cancellation does not pause a live campaign, reverse prior changes, compensate a partial graph, delete native assets, refund quota or prove delivery. It remains available with native writes/creation/spend disabled. Use the separate reviewed native status workflow to pause a campaign already running.
Cancel a queued outbound email
Owner/admin clients can POST email/operations/{id}/cancel-send, call SDK cancelEmailSend or action-enabled MCP cancel_email_send with expected_action:send,reply,forward or send_draft and confirm_cancel:true. Both email:operations:read and email:send are required, including current MCP consent. The operation lock serializes cancellation with native start: only pending/leased work before the current request starts can be cancelled. Started, ambiguous and other terminal outcomes return a conflict. Success returns status:cancelled and future_attempts_cancelled:true, clears queued content, emits one email.cancelled event and preserves the original idempotency record and quota charge. Retrying cancellation reads the same receipt; it never resends. This does not recall mail, delete a native draft, confirm delivery or refund quota. Current authorized owners can stop old-key work even if providers or writes are paused. A known retry may have made an earlier native attempt; cancellation stops only future attempts.
Find pending and ambiguous work
POST ads/operations/query, email/operations/query or inbox/operations/query with customer_id and connection_id. SDK queryAdsOperations/queryEmailOperations/queryInboxOperations and read-only MCP query_ads_operations/query_email_operations/query_inbox_operations use the same contract. Each requires its matching operations:read scope. view defaults to unresolved: pending, leased and unacknowledged ambiguous work; view all includes retained terminal records. Results contain status metadata and IDs, not message/ad content, receipts, notes or credentials. Pages default to25, maximum100, newest first. Follow a15-minute opaque cursor with the identical query and caller. Current access and customer deletion are rechecked before disclosure. Native outages/disconnection do not prevent inspecting retained local status. Use the specific get-operation endpoint to inspect a receipt; a status row never authorizes an automatic retry or acknowledgment. Status changes and retention mean pagination is not a snapshot or complete archive.
Inspect uncertain outcomes
Poll ads/operations/{id} with ads:operations:read. Accepted and succeeded do not prove delivery or actual spend. An ambiguous result blocks later work for the same target; never blindly submit it again. An owner/admin can inspect native state and explicitly acknowledge the uncertainty with a note through ads/operations/{id}/acknowledge. This unblocks later work without retrying the old operation or changing its ambiguous outcome. Expected status is checked before the write, but external edits can race it.
Advertising pagination and limits
Send an unchanged request with next_cursor to continue; encrypted cursors expire after 15 minutes and are bound to the current credential generation. Reconnect or refresh requires restarting the query. Pages contain at most 100 rows. Google continuation pages make up to three bounded queries to preserve entities on the same date. Lists exclude removed Google entities and their removed parents. Reports are not a historical snapshot; absent metric rows are not fabricated. This does not include specialized asset-group reports, arbitrary breakdowns, custom attribution settings or conversion upload/management. Google DOUBLE metrics retain native JSON precision; Meta missing metrics stay null.
Native social analytics
Use POST /api/v1/projects/{project_id}/analytics/query, the SDK queryAnalytics method or MCP query_analytics with analytics:read. YouTube supports channel-owner daily/summary plus top videos, country, traffic-source, device, operating-system, demographics, retention and sharing reports. Retention requires one video; top videos are ranked by views, capped at200 and explicitly non-exhaustive. LinkedIn supports organization daily and lifetime organic share statistics; lifetime also accepts one exact share/ugcPost content_id and returns dimensions.content_id. Selected posts reject dates and preserve the native rolling12-month window. Empty responses do not prove zero activity, ownership, existence or deletion. It also supports daily organic/paid follower gains, lifetime follower facets, and page-view daily/lifetime/audience reports for approved administrators. Select organization_followers_daily, organization_followers_audience, organization_page_daily, organization_page_lifetime or organization_page_audience. Audience requires one supported breakdown, no dates/timeframe; follower facets are combined paid/organic top100 groups. Page-view unique metrics are nonadditive; native daily boundaries remain explicit with null calendar dates. Follower daily history is conservatively limited to365 days ending two UTC days before today. Daily/summary ranges are at most31 days; YouTube breakdowns accept up to366 days subject to provider constraints. Each requires separate provider analytics consent and operator enablement. Instagram Login adds summary, account_breakdown, audience and owned-media lifetime reports with instagram_business_basic and instagram_business_manage_insights. Account totals use at most31 inclusive days within90days; breakdowns explicitly choose media_product_type or compatible follower/contact dimensions. Audience uses this_week/this_month and age/city/country/gender, no dates, and returns only available top45 aggregates. Lifetime requires content_id and verifies media ownership. Current media metrics exclude associated-ad interactions; account metrics are not uniformly organic-only. Instagram media_breakdown reads one owned content_id without dates: choose story_navigation_action_type for Story navigation or action_type for Feed/Story profile_activity. Metrics default to the compatible action metric. Counts use lowercase native dimensions and a separate native_totals aggregate; missing facets remain absent and totals are never synthesized by summing them. Story expiry/viewer thresholds apply. Instagram daily supports only reach (default) via time_series over1–31 dates within90days, without content_id. Native day/end_time stays explicit with null calendar dates; do not infer UTC daily alignment, fill missing windows with zero or sum estimated reach. Ad-inclusive media totals and complete audience inventory are not claimed. Facebook daily, facebook_page_weekly and facebook_page_28d select native day/week/days_28 Page aggregates over1–31 query dates without content_id; owned-post lifetime requires content_id and no dates. Current read_insights plus pages_read_engagement are required. Native media/engagement/reaction, contact-click, profile, estimated-follow and3-second/30-second/replay video metrics are available. page_follows balance and page_video_view_time integer milliseconds are daily only. Native period/end_time stay explicit and calendar dates null; overlapping windows and unique counts must not be summed. Deprecated metrics and partial errors are rejected. Page/post figures can include ads; unique counts are nonadditive. X adds owned-post and video lifetime counters with numeric content_id and no dates. Public counters combine organic and promoted traffic; private, organic and promoted metrics are owner-only and require posts less than30days old. Select post or video metrics separately. Video totals can span multiple posts containing the same media. Both tweet.read and users.read consent are required. X media_hourly/media_daily/media_summary additionally reports one selected video media_key attached to an owned content_id over1–31 completed UTC dates. Use distinct media_period_ metrics for watch time (exact integer milliseconds), views, playback milestones and CTA clicks. Hourly and daily native starts remain explicit, missing data stays unavailable, and native totals are not bucket sums. No weekly media report, arbitrary key lookup, exclusive asset ownership or post-unique traffic claim. X daily/summary/hourly/weekly additionally reads one owned post with separate period_ metrics across1–31 completed UTC query dates. Hourly returns at most24 times the requested date count; weekly at most31 native timestamps per request. Native bucket starts and requested bounds are explicit; missing values stay unavailable. Week alignment and bucket ends are not invented. Native traffic attribution, bucket ends, complete history and account reports are not inferred.
LinkedIn member reports
Member connections can read their own aggregate or single-post daily, summary and lifetime statistics using r_member_postAnalytics. Request one native metric at a time; some metrics only support totals. Exact share/ugcPost URNs select a post. The separate memberFollowersCount metric uses r_member_profileAnalytics and supports daily or lifetime reports. These permissions are separate from organization administration and publishing.
Native metric definitions
Responses include metric definitions, units, time basis and limitations. Numeric values are strings to preserve precision; missing data is null or omitted rows, never a fabricated zero. LinkedIn likes can be negative. Daily averages, ratios and unique counts must not be added into totals. YouTube days use Pacific time; LinkedIn organization requests use UTC day boundaries; page views preserve native exclusive-start/inclusive-end semantics.
Inspect a Meta ad and its creative
POST ads/meta-ad-context, SDK queryMetaAdContext or read-only MCP query_meta_ad_context accepts customer_id, connection_id, campaign_id, ad_group_id and ad_id. Seven fixed native reads verify advertiser and parent IDs, inspect the ad's exact creative, then re-read the ad linkage and configured/effective status. Creative copy, selected targeting and beneficiary/payer names each require explicit include_body, include_targeting or include_transparency. Omitted native values remain unknown; no full creative or audience fingerprint is promised. The combined revision is distinct from configuration_revision for budget/bid context. This is sequential selected readback, not an atomic snapshot or proof an uncertain creation succeeded. Never match resources by name or automatically adopt, retry or activate an ambiguous operation from this response.
Review and change Meta spend settings
Read /ads/meta-ad-group-context or MCP query_meta_ad_group_context for selected advertiser/campaign/group settings and revision. With include_targeting:true, also inspect selected native geography/exclusions, ages, genders, configured/effective Facebook/Instagram placements, device platforms, audience automation, schedule and dynamic creative. Null remains unknown; unmodeled_fields reports field paths without audience values. The separate targeting revision does not replace the money revision or certify a complete audience review, retained creation request or safe activation. update_meta_ad_group_budget and update_meta_ad_group_bid require ads:write, ads:spend, explicit spend_authorized and reviewed currency, statuses, strategy, revision and current/proposed minor-unit amounts. Daily-budget and bid-cap edits require existing daily budgeting. update_meta_ad_group_lifetime_budget separately edits an existing positive lifetime TOTAL budget with zero daily budget and exact expected_end_time copied from context. The total is not remaining spend or an incremental allowance; Meta validates native minimum/spend limits. The existing end date must stay unchanged and at least60seconds away at the final authority fence. All three edits require the same write/spend permissions and reviewed configuration. Ordinary website traffic is the default. All three money actions also accept expected_conversion:{pixel_id,event_type,confirm_website_conversion:true} after explicit include_conversion review for an existing simple Sales/OFFSITE_CONVERSIONS group. Budget edits preserve reviewed lowest-cost or existing bid-cap strategy; bid edits require a positive existing LOWEST_COST_WITH_BID_CAP amount. Omit expected_end_time for daily-budget groups; explicitly supply the exact reviewed canonical UTC end date to select lifetime-budget bid editing. The positive lifetime total and end date stay unchanged, daily budget must be zero, and more than60seconds must remain after the final authority wait. A fresh fourth native GET requires exact advertiser/parent/pixel/event and rejects rules, custom conversions and unmodeled fields before the final authority fence, including unchanged amounts. Native strategy must match the review, and capped Sales groups require a positive current cap. A cap is an auction input, not a charged-cost or spending ceiling. No tracking event, pixel, attribution or strategy change is added. Receipts report reviewed_conversion and native_conversion_verified:false. Campaign budgets, budget-type conversion, sharing, scheduling and accelerated pacing are refused. Each edit sends one field, with no status or strategy change. Acknowledgment is not readback or guaranteed delivery; inspect the context again and never blindly replay an uncertain write.
Review selected conversion settings
Use include_conversion:true independently on ads/meta-ad-group-context or ads/meta-ad-context, the matching SDK method or read-only MCP tool. The exact authorized advertiser/campaign/group must match. Selected nullable pixel/custom-conversion IDs, custom-event type and native attribution event/window pairs are returned with a separate conversion revision; omission suppresses them. Rules, custom-event text, names, URLs and event payloads are excluded. Current settings do not prove exclusive ownership, eligibility, effective or historical attribution, event ingestion or complete configuration. Money revisions remain unchanged. This read does not create conversion campaigns, upload events or authorize spending.
Inspect Meta pixels
Use ads/meta-assets, SDK queryMetaAssets or read-only MCP query_meta_assets with resource:pixels, customer_id and connection_id. Requires current ads:read, native advertiser read permissions and customer authority. Lists contain at most50 records; names require include_names:true. Selected nullable native creation/last-fired timestamps and availability/restricted-use flags describe returned metadata only. account_id is the queried advertiser edge, not verified exclusive ownership. Explicit ownership, advertising eligibility and event-ingestion verification flags remain false. Tracking code, event data and configuration are excluded. Continue using the unchanged query and encrypted next_cursor; access or credential changes withhold the response. This does not install tracking, create pixels, ingest events or authorize conversion advertising.
Not yet supported
Broader creative/media formats, other campaign objectives, additional targeting/bidding, audience creation/uploads, pixel creation/tracking/event ingestion, custom-conversion creation/uploads and other advertising networks remain outside the implemented contract. Techrace does not currently provide complete organic social or inbox analytics.
Keep credentials separate
Social publishing permission is not automatically advertising permission. Grant the ad-specific scopes your app needs and keep requests within the authorized customer and account.
Interpret reports carefully
Provider attribution windows, reporting delay, time zones, currencies and metric definitions can differ. Preserve provider context when displaying comparisons in your product.
These guides describe implemented code and operating requirements. Enabled capabilities and permissions may differ. Use the current API specification and your project’s capability view.
OpenAPI specification