Manage GAM first-party audience segments.

MODE: mixed (read + write) AUTH: OAuth 2.0 required — call initiate_gam_auth first CREDITS: list/get = 0 credits (free). create_audience_segment = 0.5 credits and requires a confirmation_token. OUTPUT: Returns audience segment objects with id, name, status, membershipExpirationDays, and eligibilityCriteria. SIDE EFFECTS: create/update modify GAM network data. perform_audience_segment_action can activate or deactivate segments. WHEN TO USE: Use this tool for managing first-party data segments (CRM lists, pixel-based audiences). For targeting existing segments on line items, use the targeting tool instead.

Query the GAM audit log for change history.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns a list of AuditEvent objects with entityId, entityType, changeType, userId, timestamp, and a diff of changed fields. WHEN TO USE: Use audit when you need to trace who changed what and when on a specific GAM entity (order, line item, creative, ad unit). NOT the same as audit_skill: audit queries the GAM change log; audit_skill runs proactive quality/compliance checks. NOT the same as gam_audit: gam_audit runs a full network-wide compliance report; audit queries history for a specific entity.

OrbiAds proactive audit suite — six sub-actions for quality and compliance analysis.

MODE: read-only (all actions are non-destructive analysis) AUTH: OAuth 2.0 required CREDITS: 0 (all actions free) OUTPUT: Returns a structured markdown report with findings, severity levels (CRITICAL/WARNING/INFO), and recommended remediations. WHEN TO USE: Use audit_skill to proactively detect problems before they impact delivery. • Use hygiene_check for routine health checks (orphaned creatives, stalled orders, mismatched budgets). • Use standards_baseline to verify compliance against a named framework (ISO 27001 ad-ops, IAB, NIST). • Use wrapper_coverage to audit creative wrapper deployment across ad units. • Use estimate_cost to preview credit costs before running expensive operations. NOT the same as audit: audit queries GAM change history; audit_skill analyzes current state. NOT the same as gam_audit: gam_audit is a convenience wrapper combining hygiene_check + ops_diagnostic + standards_baseline in one call.

Inspect OrbiAds account billing — credit balance and transaction history.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: get_credit_balance returns {balance: float, plan: string, monthly_allowance: int}. list_transactions returns paginated list of {date, type, amount, description, balance_after}. WHEN TO USE: Call get_credit_balance before write operations to confirm sufficient credits. Use list_transactions for usage auditing.

Manage the tenant inventory blueprint — the canonical definition of ad formats, positions, key-values, and brand settings used to generate GAM campaigns.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes (save_blueprint, save_preferences, add/remove operations) = 0 credits but modify persistent tenant configuration. OUTPUT: get_active_blueprint returns the full blueprint JSON with formats, positions, keyValues, brand. list_templates returns available campaign templates. SIDE EFFECTS: Changes to the blueprint affect all future campaign deployments that reference it. Removing a format or position does not remove existing GAM line items. WHEN TO USE: Use blueprint to define or update the standard inventory structure before running campaign. Use formats tool for the Custom Format Registry (creative format recipes, not inventory positions).

Orchestrate GAM campaign lifecycle — the primary write surface for creating and managing campaigns.

MODE: write-heavy (most actions modify GAM data) AUTH: OAuth 2.0 required CREDITS: deploy = 2–5 credits depending on line item count. Other write operations = 0.5–1 credit. Reads = 0. CONFIRMATION TOKEN: deploy and rollback require a confirmation_token obtained from a prior dry-run preview. This prevents accidental deployment. OUTPUT: deploy returns {campaign_id, order_id, line_item_ids[], creative_ids[], status}. rollback returns {reverted_to_version, entities_affected}. SIDE EFFECTS: deploy creates Order + LineItems + Creatives + LICAs in GAM — irreversible without rollback. rollback archives the current version and restores the previous one. WHEN TO USE: Use campaign for end-to-end campaign creation from a blueprint. Use line_items or orders for surgical updates to existing campaigns. DESTRUCTIVE: rollback and archive are non-trivial — they modify live GAM entities.

Manage GAM companies — advertisers, agencies, and contacts.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes (create, update, archive) = 0.5 credits. OUTPUT: Returns Company objects with id, name, type (ADVERTISER/AGENCY/HOUSE_ADVERTISER), creditStatus, address, and associated contacts. SIDE EFFECTS: archive_advertiser deactivates the company and prevents new orders from being created under it. Does not delete historical data. WHEN TO USE: Use companies to manage the advertiser/agency entities required before creating orders. An order must be linked to an advertiser.

Upload and create GAM creative asset files — images, HTML5, video, audio, and companion ads.

MODE: write (all actions upload or create assets) AUTH: OAuth 2.0 required CREDITS: 0.5 credits per upload/create action. OUTPUT: Returns CreativeAsset objects with assetId, fileName, fileSize, mimeType, and a preview URL. SIDE EFFECTS: Assets are stored in GAM and consume storage quota. compress_image modifies the asset file in-place. WHEN TO USE: Use creative_assets for asset file management (uploading raw files). Use creatives for full Creative entity management (associate assets with creative templates). Use creative_qa to validate assets after upload.

Creative quality assurance — validate, scan, and pre-check creatives before and after trafficking.

MODE: read-only (all actions are non-destructive analysis) AUTH: OAuth 2.0 required CREDITS: 0 (all free) OUTPUT: Returns a QA report with pass/fail status per check, severity (CRITICAL/WARNING/INFO), and specific issue descriptions with remediation guidance. WHEN TO USE: Run creative_qa after uploading creative assets and before activating line items. Use pre_archive_check before archiving a creative to detect active associations. NOT the same as audit_skill: audit_skill checks network-wide operational health; creative_qa focuses specifically on individual creative compliance.

Manage GAM CreativeWrapper entities — wrappers that inject scripts around all creatives served on an ad unit or placement.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns CreativeWrapper objects with id, name, adUnitId or placementId, headerHtmlSnippet, footerHtmlSnippet, and ordering. SIDE EFFECTS: Active CreativeWrappers apply globally to every creative served on the targeted ad unit/placement. Misconfigured wrappers can break ad serving. Test in a staging network first. WHEN TO USE: Use for injecting site-wide measurement scripts, viewability tags, or brand safety layers. Use presets for reusable wrapper templates.

Manage GAM Creative entities and native styles — full lifecycle from list to archive, plus LICA management.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. Bulk operations = 0.5 credits flat. OUTPUT: Returns Creative objects with id, name, type, size, previewUrl, and associated assetIds. Preview URLs expire after 24h. WHEN TO USE: Use creatives for Creative entity management (metadata, associations, lifecycle). Use creative_assets for raw asset file uploads. Use creative_qa for compliance validation. NOTE: A Creative entity in GAM wraps one or more creative_assets. A LICA (LineItem-Creative Association) links a Creative to a LineItem for serving.

Author and manage programmatic deals — PMP, PG/PD proposals, ADCP deal flows, and auction packages.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Write operations = 0.5–2 credits. ADCP create = 2 credits. OUTPUT: Returns Deal or Proposal objects with id, status, buyerId, floorPrice, targeting, and negotiation state. SIDE EFFECTS: Proposals go through a negotiation workflow — state transitions (reserve, request_buyer_acceptance) trigger buyer notifications. terminate_proposal_negotiations is irreversible. WHEN TO USE: Use deals for programmatic direct (PG/PD), private marketplace (PMP), and ADCP deal creation. For standard direct-sold campaigns, use campaign tool instead.

Manage the Custom Format Registry — reusable creative format recipes with multi-site scope.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0 credits (config changes only). OUTPUT: Returns Format recipe objects with id, name, dimensions, creative_type, and applicable_sites. WHEN TO USE: Use formats to define reusable creative format specifications (e.g., a 300x250 standard display recipe) that can be applied across multiple GAM networks. NOT the same as blueprint: blueprint defines inventory positions; formats defines creative format specifications. NOT the same as creative_assets: creative_assets manages uploaded files; formats manages format metadata.

GAM admin orchestration — 48 operations across 7 administrative areas: Teams, Sites, Mobile Apps, Custom Fields, Labels, Publisher Provided Signals, and Users.

MODE: mixed (read + write) AUTH: OAuth 2.0 required — user must have Network Admin role for write operations CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns administrative entity objects specific to the sub-area (Team, Site, MobileApp, CustomField, Label, PublisherProvidedSignalsConfig, User objects). SIDE EFFECTS: User management operations (deactivate, remove) affect access control. Label and custom field changes propagate to existing entities. Team changes affect inventory access rights. WHEN TO USE: Use gam_admin for network configuration and governance tasks (team structure, user management, custom metadata). Use targeting for custom targeting key-values used in ad serving.

Inspect GAM network features — discover which beta features and capabilities are enabled.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns a list of NetworkFeature objects with featureName, enabled (boolean), and description. WHEN TO USE: Call before using advanced GAM features to verify they are enabled on the network. Use probe_gam_features when you need to test a specific capability live.

Poll and manage async GAM background jobs.

MODE: read-only (polling only — jobs are created by other tools) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns Job objects with id, type, status (PENDING | RUNNING | COMPLETE | FAILED), progress (0–100), result_url or result_data, and error if failed. WHEN TO USE: Use after starting a long-running operation (e.g., large inventory scan, bulk line item creation) that returns a job_id. Poll until status = COMPLETE or FAILED.

Manage GAM ad unit inventory — tree traversal, audit, batch creation, ads.txt, and blueprint sync.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5–1 credit. OUTPUT: get_ad_unit_tree returns a hierarchical JSON of ad units. audit_inventory returns an analysis report. create_ad_units_batch returns a list of {requested_name, created_id, status}. SIDE EFFECTS: push_inventory_blueprint creates or updates ad units in GAM based on the stored blueprint. archive_inactive_ad_units is destructive and cannot be undone. WHEN TO USE: Use inventory for ad unit structure management. Use targeting for custom targeting keys. Use blueprint for the canonical format/position definition that drives inventory creation.

Manage OrbiAds campaign deployment jobs — distinct from GAM background jobs (use gam_jobs for those).

MODE: read + limited write AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns OrbiAds Job objects with id, campaign_id, status, created_at, and deployment log. WHEN TO USE: Use jobs to check the status of an OrbiAds campaign deployment job. Use gam_jobs to poll GAM-native background operations. NOT the same as gam_jobs: jobs tracks OrbiAds deployment pipelines; gam_jobs tracks GAM server-side async jobs.

Non-lifecycle Line Item operations — get, list, update, duplicate, verify, and create programmatic types.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns LineItem objects with id, name, type, startDateTime, endDateTime, costType, unitsBought, targeting, and deliveryIndicator. WHEN TO USE: Use line_items for individual line item CRUD and programmatic line item creation. Use campaign for full campaign orchestration. Use line_item_lifecycle for status transitions (activate/pause/archive). NOT the same as line_item_lifecycle: line_items handles data updates; line_item_lifecycle handles status transitions.

GAM network management — get info, switch active network, list accessible networks, update settings.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. update_network = 0.5 credits. OUTPUT: get_network_info returns {networkCode, displayName, currencyCode, timeZone, effectiveRootAdUnit}. list_accessible_networks returns all networks the authenticated user can access. WHEN TO USE: Use network to discover and switch between multiple GAM networks. Call list_accessible_networks after authentication to find available networks, then switch_network to set the active one.

Non-lifecycle Order operations — list, get, create, update, and manage orders.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns Order objects with id, name, status, advertiserId, agencyId, salespersonId, traffickerId, totalBudget, and startDateTime/endDateTime. WHEN TO USE: Use orders for Order entity management. Use campaign for full campaign orchestration that includes Order + LineItems. Use order_lifecycle for status transitions. NOT the same as order_lifecycle: orders handles data; order_lifecycle handles approve/archive/disapprove transitions.

Manage GAM placements — named groups of ad units used for targeting.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns Placement objects with id, name, description, targetedAdUnitIds, and status. WHEN TO USE: Use placements to create named groupings of ad units for targeting in line items. Placements are referenced in line item targeting via the targeting tool. Use inventory for individual ad unit management.

Execute PQL (Publisher Query Language) queries against GAM reporting tables.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns a ResultSet with column definitions and rows. Each row is an array of values matching the column order. WHEN TO USE: Use pql for ad-hoc data extraction not covered by the reporting tool's structured reports. LIMITATIONS: Not all PQL tables are available on all networks (some require beta features). The Language and Device_Category tables have known limitations. For structured delivery/inventory reports, use reporting instead.

Generate creative and campaign preview URLs and validate creative coverage.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns preview URLs (expire after 24h) and coverage reports listing which line items have zero or insufficient creative associations. WHEN TO USE: Use preview before launching a campaign to verify all creatives render correctly and coverage is complete.

Manage GAM Products and Product Packages for programmatic direct deals.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns Product objects with id, name, type, rateType, rate, targeting, and status. WHEN TO USE: Use products to manage the GAM product catalogue for Programmatic Direct (PD) deals. Products define the inventory packages offered to buyers. For creating deals from products, use the deals tool.

Full GAM and GA4 reporting — delivery reports, custom reports, forecasting, traffic data, and billing.

MODE: read-only (reports are read operations; report templates are saved configuration) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Delivery/custom reports return rows of dimension+metric values. Forecasts return estimated_impressions, estimated_clicks, and confidence intervals. Report templates return template objects for reuse. WHEN TO USE: Use reporting for all data extraction and analysis. Use reporting_skill for high-level multi-step reporting workflows described in natural language. • For delivery analysis: check_delivery_status or fetch_delivery_report. • For custom ad-hoc reports: run_custom_report. • For forecasting: get_standalone_forecast or get_delivery_forecast_by_line_item. • For GA4 data: run_ga_report. • For reusable reports: save/run report templates. LIMITATIONS: Some SOAP-era metrics (TOTAL_*, AD_SERVER_ALL_REVENUE) and dimensions (MONTH_AND_YEAR, CREATIVE_SIZE) are rejected by the REST API. Use get_report_dimensions/get_report_metrics to discover valid options.

Manage OrbiAds tenant settings — naming conventions, delivery defaults, and configuration presets.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0 credits (configuration only). OUTPUT: Returns settings objects with key-value pairs for naming patterns, delivery parameters, and preset configurations. WHEN TO USE: Use settings to configure tenant-level defaults that apply across all campaigns. For network-level GAM settings, use the network tool.

Manage GAM custom targeting keys, values, and ad unit targeting configuration.

MODE: mixed (read + write) AUTH: OAuth 2.0 required CREDITS: Reads = 0. Writes = 0.5 credits. OUTPUT: Returns CustomTargetingKey objects with id, name, type (PREDEFINED/FREEFORM), and associated values. get_available_countries/languages/devices return canonical lists for geographic/device targeting. WHEN TO USE: Use targeting to manage the custom targeting vocabulary (keys and values) used in line item targeting. Use line_items to apply targeting to line items. Use inventory for ad unit structure. NOTE: get_inventory_forecast takes targeting criteria and returns estimated available impressions — useful before creating a line item to verify reach.

Scan and cache the tenant's GAM inventory catalog for fast downstream operations.

MODE: read (scan triggers a background read job) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: get_active_catalog returns a JSON catalog of ad units, placements, and key-values. get_scan_status returns {status: IDLE|RUNNING|COMPLETE, progress, last_updated}. WHEN TO USE: Run scan_network once after connecting a new GAM network, then call refresh periodically (daily) to keep the catalog current. Other tools use the catalog for fast lookups without hitting the GAM API on every call.

Return the OrbiAds tenant ID for the authenticated session.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns {tenant_id: string} WHEN TO USE: Call this first in any workflow to resolve your tenant_id. The tenant_id is required by some internal operations and for multi-tenant debugging.

Start the OAuth 2.0 authorization flow to link a GAM network to the OrbiAds tenant.

MODE: write (creates a pending auth session) AUTH: Partially authenticated (OrbiAds session required, GAM auth not yet established) CREDITS: 0 (free) OUTPUT: Returns {auth_url: string, session_id: string}. Open auth_url in a browser and authorize. Then poll poll_auth_status with the session_id. WHEN TO USE: Call when a GAM network has not yet been authorized (check_credentials returns false). Do not call if credentials are already valid.

Poll the OAuth authorization status after initiating a GAM auth flow.

MODE: read-only AUTH: OrbiAds session required CREDITS: 0 (free) OUTPUT: Returns {status: 'pending'|'authorized'|'failed', error?: string} WHEN TO USE: Call repeatedly (every 2–5 seconds) after initiate_gam_auth until status = 'authorized' or 'failed'.

Set the active GAM network for the current session when the tenant has multiple linked networks.

MODE: write (session state change) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns {network_code: int, display_name: string, currency: string} WHEN TO USE: Call after authentication when the tenant has more than one GAM network linked. All subsequent tool calls will use this network_code unless overridden per-call.

Perform lifecycle status transitions on a GAM Line Item (activate, pause, archive, resume).

MODE: write AUTH: OAuth 2.0 required CREDITS: 0.5 credits. Confirmation token required for archive. OUTPUT: Returns {line_item_id, previous_status, new_status} WHEN TO USE: Use this for status transitions only. For data updates (targeting, budget, dates), use the line_items update action. DESTRUCTIVE: archive cannot be undone from the API.

Perform lifecycle status transitions on a GAM Order (approve, archive, disapprove).

MODE: write AUTH: OAuth 2.0 required CREDITS: 0.5 credits. Confirmation token required for archive. OUTPUT: Returns {order_id, previous_status, new_status} WHEN TO USE: Use this for order status transitions. For data updates, use the orders update action. DESTRUCTIVE: archive stops all line item delivery under the order.

High-level reporting orchestration — describe a reporting goal in natural language and get results.

MODE: read-only (orchestrates multiple reporting tool calls internally) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns a formatted report with dimensions, metrics, and data rows. May include charts or summary analysis. WHEN TO USE: Use reporting_skill when the reporting goal is clear but the exact dimension/metric combination is unknown. It internally calls get_report_dimensions, get_report_metrics, and run_custom_report. Example: "weekly revenue by ad unit for last month" → selects AD_UNIT_NAME + TOTAL_LINE_ITEM_LEVEL_REVENUE automatically. NOT the same as reporting: reporting gives direct access to individual report operations; reporting_skill is a higher-level orchestrator.

Verify that the GAM OAuth credentials for a network are still valid and have required scopes.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns {valid: boolean, scopes: string[], expires_at: datetime, error?: string} WHEN TO USE: Call at the start of a session to verify credentials before running operations. If valid=false, call initiate_gam_auth to re-authorize.

Revoke and permanently remove the GAM OAuth credentials for a network from the tenant.

MODE: write (destructive) AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns {network_code, disconnected_at} SIDE EFFECTS: All OrbiAds operations requiring this network will fail after disconnection. The network must be re-authorized via initiate_gam_auth to restore access. WHEN TO USE: Use when intentionally removing a network from the tenant (e.g., end of contract). Confirmation token required — this action is irreversible via API.

Run a full GAM network compliance audit combining hygiene, diagnostics, and a standards baseline in one call.

MODE: read-only AUTH: OAuth 2.0 required CREDITS: 0 (free) OUTPUT: Returns a comprehensive markdown report with: (1) hygiene findings, (2) operational diagnostics, (3) standards baseline results per framework control. Overall pass/fail verdict included. WHEN TO USE: Use gam_audit for a complete one-shot network audit. For individual audit components, use audit_skill with the specific action. NOT the same as audit: audit queries change history; gam_audit analyzes current state. NOT the same as audit_skill: gam_audit is a convenience wrapper that calls hygiene_check + ops_diagnostic + standards_baseline in sequence.