site_seo_metrics | The cached SEO authority metrics for a hosted site — domain rank, backlinks, referring domains and organic keywords. Read-only and free; the figures are refreshed by the platform's own sweep, so they may be up to a month old. | sites.view | فقط می‌خواند |
domain_index_check | The cached search-index status for a domain — whether it is indexed, how many pages, and when the reading was taken. Read-only and free. | sites.view | فقط می‌خواند |
ads_connections_list | List the organisation's connected Zinn® Ads ad accounts (Google Ads): status, the mode per action class (approve first, automatic, off), spend ceilings and how many changes wait for approval. | ads.view | فقط می‌خواند |
ads_changes_list | List Zinn® Ads changes to the organisation's ad accounts: 'pending' ones wait for approval; 'applied' ones say whether they can still be undone (30 days). | ads.view | فقط می‌خواند |
ads_change_decide | Approve (it is then sent to Google), reject, or undo one Zinn® Ads change by id. A kill switch or a spend ceiling can still stop an approved change. | ads.manage | چیزها را تغییر می‌دهد |
ads_kill_switch | Turn the organisation's Zinn® Ads kill switch on (nothing is changed in any of its ad accounts; Undo still works) or off. | ads.manage | چیزها را تغییر می‌دهد |
ads_connection_settings | Change one connected ad account's autopilot settings: per kind of change (negatives, keywords, pauses, budgets, bids, exclusions, campaigns, ads, assets, audiences, conversions) approve / auto / off; daily and monthly spend ceilings in minor units of the account's currency; hold_until_sale; roas_target_pct (400 = 4.0x); markets [{country, language}]; excluded_countries [ISO codes never served]; country_waste_mode suggest / auto / off (exclude countries that spend with no activation or sale); competitor_automation; new-country campaigns (auto_new_countries, new_country_max_per_month 0-10, new_country_budget_minor a day, new_country_min_conversions, new_country_min_clicks — proposed for approval unless campaigns are 'auto'); auto_cap_raise (default on: +20% CPC cap for a converting campaign losing on price, inside the ceiling); budget raises for converting campaigns held back by budget: budget_raise_mode auto / suggest / off, budget_raise_scope all / campaigns, budget_raise_campaigns {campaign id: mode}; month-end spend pacing: pacing_mode auto / suggest / off (correct the budgets inside the ceiling, suggest it, or only warn), pacing_deviation_pct 5-50 (the drift that warns), pacing_target_minor (the month's target, null = what the budgets plan); pacing_strategy even / day_of_week / front_loaded, pacing_change_cap_pct 5-50 (the most one run changes a budget), pacing_rollover (carry last month's unspent target), pacing_pause_over (pause the spending campaigns once the month spent its ceiling, resumed on the 1st), pacing_minimums {campaign id: minor units} (a cut never goes under it). tidy_paused_days (1-365, null = off, the default) deletes an ad paused that many days, tidy_paused_mode suggest (queued for approval) or auto (each delete keeps its Rebuild). The signal ladder: business_type free_trial / freemium / lead_gen / ecommerce / local / b2b ('' = not chosen) and ladder_signals {"1"|"2"|"3": [conversion action resource names]} — which actions are the sign-up, activation and paid signal (a stage left out follows the business type); campaign_ladder {campaign id: {business_type, signals}} judges one campaign differently (hosting on a real domain live, plugins on installs). conversion_lag_days (1-90, null = off) is the customer's own trial or sales window: a sale verdict waits for trials and leads still inside it. cta_words (up to 10) are the words a landing-page button must say ('Book a call'); a page with none is flagged. Only what is given changes. 'auto' needs a plan with autopilot (Starter or above); several languages and competitor campaigns need Pro or above. Every change is audit-logged. | ads.manage | چیزها را تغییر می‌دهد |
ads_connect_link | Get the sign-in link that connects Google Ads (default), Microsoft Advertising (platform=microsoft) or X Ads (platform=x) accounts to Zinn® Ads. A person must open it in a browser and pick the accounts; this call alone connects nothing. | ads.manage | چیزها را تغییر می‌دهد |
ads_audit_run | Run one connected ad account's audit now (Google Ads, Microsoft Advertising or X Ads). Every change it finds (negatives, keywords, pauses) waits in the approval queue unless that kind of change is set to automatic. Returns at once; the changes it finds appear in the approval queue. | ads.manage | چیزها را تغییر می‌دهد |
ads_shield_clicks | The Zinn® Ads click-fraud shield for the organisation's sites hosted by Zinn®: the period totals (clicks, suspected invalid, converted, reasons, ESTIMATED wasted spend in minor units) and the latest scored paid clicks. Estimates only: Google decides what is invalid and nothing here promises a refund. | ads.view | فقط می‌خواند |
ads_shield_exclusions | What the Zinn® Ads click shield did at Google for the organisation: the IP and placement exclusions it asked for per campaign (each an ad-account change: approve-first unless exclusions are automatic, undoable for 30 days; IPs shown as their network only), and the monthly refund evidence packs per Google Ads account with any credit Google gave. Packs are never filed automatically: a person sends one through Google's form. | ads.view | فقط می‌خواند |
ads_tracking | For one connected ad account: its real outcomes (sales, trials, leads, sign-ups from the customer's own store, plugin, CRM or the events API) against what the network credited over the settled days, whether the autopilot is HOLDING (tracking more than 10% apart, or the network unreadable: nothing is judged, cut or paused on its counts), what the check found (lost click ids, checkout round-trips, off-site outcomes, missing tag, upload action not counting) and the recovery's before/after, plus the 'Fix it for me' add-on price when it is offered. | ads.view | فقط می‌خواند |
ads_budget_moves | Answered from the daily audit's stored findings (no network call): for one connected Google Ads account, every campaign held back by its budget with the proposal — 'move X/day from A to B' naming the donor and why it can give (held back by ad rank, under-spending, low return), the receiver's share lost to budget, the clicks and conversions the money buys at its own cost per click and conversion rate, the 'increase' option when the ceiling has room, or why there is no move (no return yet, learning, an owner hold). Apply one with the findings apply operation (option move | increase); nothing here changes the account. | ads.view | فقط می‌خواند |
ads_tracking_check | Run one ad account's tracking truth check now, then upload the real outcomes the network missed (each once, deduplicated by its own order or trial id, within 90 days). recovery_mode 'validate' makes the network check the upload and keep nothing. Returns at once; the result appears on the account's tracking check a moment later. | ads.manage | چیزها را تغییر می‌دهد |
ads_insights | For one connected Google Ads account, the latest daily readings: where this month's spend will end against its target (and any budget correction made or waiting for approval, inside the spend ceiling); any conversion action that stopped recording against its own baseline, with how to fix it; and the clicks and conversions each campaign missed in the last 7 days because of its budget or ad rank (estimates), with the one fix (a bigger budget, a higher bid cap, better ad rank); and the signal ladder: each campaign's stage (1 learn on sign-ups, 2 activate, 3 earn on paid sales), what the next stage still needs, and whether each stage's signal is proven recorded. | ads.view | فقط می‌خواند |
ads_autopilot | For one connected ad account (za-14): each step the autopilot runs on it — add a wasteful search term as a negative keyword, pause a keyword that spent its maturity clicks with no conversion, add a converting search term as a phrase keyword, keep budgets inside the account's own monthly ceiling (za-67), move a campaign up the bid-strategy ladder (za-68, automatic only) — with the account's mode for it: auto (sent, 30-day Undo), approve (kept as a change waiting for approval) or off (never tried); and what the latest finished audit did. Every write still passes the account's guards (good standing, spend ceilings, hold until a sale, ROAS target). The modes are the account's autopilot settings. | ads.view | فقط می‌خواند |
ads_outcomes_record | The events API as a tool: record up to 500 real outcomes for one ad account — kind (purchase, trial, lead, signup, activation — the step after a sign-up that predicts a sale, e.g. the plugin installed or the first site live), your own order or trial id (external_ref), when it happened, value in minor units + currency, and the ad click id it came with (gclid, gbraid, wbraid or msclkid). The same order twice is stored once. A plain e-mail is hashed and dropped. | ads.manage | چیزها را تغییر می‌دهد |
ads_plan | Which Zinn® Ads plan the organisation is on (Free, Starter, Pro or Agency), how many ad accounts it may connect and has connected, the monthly ad spend it may have managed across all its accounts and how much is set now, the Extra accounts (+10, $49/mo) and Extra spend (+$25k, $99/mo) add-ons it holds, any automatic Agency overage (+$99 per extra $25k), whether autopilot and the click shield are included, and the plans it can move to, each with the dashboard link that buys it (the Free plan costs nothing). | ads.view | فقط می‌خواند |
ads_builds | The organisation's Zinn® Ads Simple-mode plans (website + monthly budget + markets -> a whole Google Ads account plan): status, and for one plan ('build_id') its campaigns, keywords with measured volume and CPC (minor units), negatives, ads quoted from the site, policy findings and the forecast range. Reading only; nothing reaches Google. | ads.view | فقط می‌خواند |
ads_build_create | Start a Zinn® Ads Simple-mode plan: read the website, then (once its 'what do you sell' is confirmed) research keywords per market and write the plan. 'monthly_budget_minor' is integer minor units of 'currency'; 'markets' is a list of {country (ISO alpha-2), language}. Building costs research and AI credits; launching it is a person's click in the dashboard and only queues changes for approval. | ads.manage | چیزها را تغییر می‌دهد |
ads_ads_list | For one connected Google Ads account: its campaigns, ad groups and ads (not removed) with their status, read from Google now — each ad with its headlines, descriptions, final URL, ad strength and whether it can be rebuilt after a delete. paused_only=true lists only the paused ads (what 'Delete all paused ads' would delete). | ads.view | فقط می‌خواند |
ads_ad_action | Pause, unpause or delete one ad, ad group or campaign of a connected Google Ads account (its resource name, as the list tool returns it). Delete is for a PAUSED ad or ad group only: its snapshot (headlines, descriptions, paths, final URLs, keywords) is saved and the change's undo REBUILDS it as a new paused copy; a deleted ad itself cannot be brought back. Pause and unpause can be undone. The kill switch still stops it. | ads.manage | چیزها را تغییر می‌دهد |
ads_paused_ads_delete | Delete every ad that is PAUSED right now in one connected Google Ads account (or only the resources given, as the list tool returns them with paused_only). Each ad's snapshot is saved and each delete's undo rebuilds it as a new paused copy. Sent in the background. | ads.manage | چیزها را تغییر می‌دهد |
ads_negative_conflicts | For one connected Google Ads account: every negative keyword (campaign, ad group, negative keyword list or account level) that blocks one of the account's own enabled keywords, as found by the daily audit — what it blocks, the decision (pause the keywords when the negative is deliberate, otherwise narrow it to exact match or remove it), why, and the id of the change in the approval queue to approve or reject. New negatives that would block a keyword are refused before they are sent. | ads.view | فقط می‌خواند |
ads_bid_ladder | For one connected ad account (Google or Microsoft), each campaign's bid strategy on the ladder (Maximise clicks → Maximise conversions → target CPA, or target ROAS when its conversions carry values) and the verdict: up / down (a switch is proposed), not_yet (with the conversions it has and the network's published minimum plus our 1.5 margin), top, learning (switched in the last 14 days: no automatic budget raise, bid or keyword change touches it until frozen_until) or kept; and the measured result 14 days after a switch. Answered from the daily audit's rows, never a network call. | ads.view | فقط می‌خواند |
ads_bid_strategy_switch | Move one campaign of a connected ad account the step its bid-ladder row proposes (only when its verdict is up or down). The switch is approved and sent through the same gate as every change (kill switches, good standing) with a 30-day undo; the campaign then learns for 14 days with no automatic budget, bid or keyword change. | ads.manage | چیزها را تغییر می‌دهد |
ads_objective_set | Propose the objective one campaign of a connected ad account is judged against (OBJ1, za-184): leads (target_cpa_micros), revenue (target_roas_pct, 400 = 4.00x), profit (margin_pct; the target return is break-even), top_of_page (share_pct, placement anywhere/top/absolute_top, max_cpc_micros), brand_defence (max_cpc_micros; 90% at the absolute top unless given), traffic (optional max_cpc_micros) or none. Approve-first: the proposal changes nothing until a person approves it on the Zinn® Ads screen; then the bid-strategy ladder steers towards it, one step at a time on the networks' minimums, never while the campaign learns, and every switch is its own change with an Undo. Money is integer micros of the account's currency. | ads.manage | چیزها را تغییر می‌دهد |
ads_acquisition_quality | For one connected ad account, each keyword, ad group and country that acquired paid customers: how many paid, how many went bad (refunded, charged back, cancelled early or heavy on support — on a customer's account its checkout connectors report refunds only), its bad-customer rate against the rest of the account in basis points, and the verdict: finding (a one-click suggestion to pause it or exclude the country, approve first, with Undo), owner_locked, or held (held_sample under 3 bad customers, held_baseline, held_rate). Answered from the daily audit's report, never a network call; no buyer is ever named. | ads.view | فقط می‌خواند |
ads_placement_goals | Every top-of-page goal of a connected ad account (TOPPAGE1, za-187): each campaign's main keywords, its target share of the top (or absolute top) of the page, its max CPC and daily budget, and the daily audit's latest reading — the share measured, the verdict (on_target / off_target / no_data) and, below target, the causes in order (ad relevance, landing page, expected CTR, then bid or budget) with each fix priced from the ad network's own top-of-page bid estimates. It changes nothing. Money is integer micros. | ads.view | فقط می‌خواند |
ads_placement_goal_set | Set (or, with remove=true, remove) the top-of-page goal of one campaign of a connected ad account (TOPPAGE1, za-187): keywords (its main keywords, at most 20), share_pct (the target share, 1-100), placement (top or absolute_top), optional max_cpc_micros and daily_budget_micros (0: let Zinn® Ads price them from the network's top-of-page bid estimates). A goal sends nothing to the ad account: the daily audit measures it and, below target, proposes its fixes for a person to apply, each with its Undo. | ads.manage | چیزها را تغییر می‌دهد |
ads_findings | For one connected Google Ads account: everything the daily audit found — wasted searches, dead campaigns (spend with no install, activation or sale), campaigns limited by budget or rank, the month's run rate against the ceiling with its pacing verdict (a trim that lands the month inside it, or raises held when no safe trim fits), and the rest — each with its reason code, its figures (campaign, spend, clicks, days) and whether it is an open one-click suggestion or a change the autopilot already made (with its Undo). Reading only; nothing reaches Google. | ads.view | فقط می‌خواند |
ads_allowed_terms | For one connected Google Ads account: every other company's name the account allows in ONE ad group's ad text (an 'alternative to X' or 'X vs Y' group), with the group and the allowance id. Every other ad group keeps refusing that name: no ad text may name a competitor except where the account allows it. Reading only. | ads.view | فقط می‌خواند |
ads_allowed_term_set | On one connected Google Ads account: 'allow' lets ONE ad group's ad text name another company (give ad_group_id, as the ads list tool returns it, and term, the company name); 'withdraw' removes an allowance by its id (as the allowed-names listing returns it). The name stays refused in every other ad group. Every allow and withdraw is audit-logged. | ads.manage | چیزها را تغییر می‌دهد |
ads_landing_pages | For one connected Google Ads account: every enabled ad's final URL as the daily audit last checked it on a phone (status, redirect, language, main heading, whether the call to action is in the first screen, mobile LCP/CLS) and each problem found with its concrete fix: broken or redirecting pages, wrong language, a competitor ad landing on a page that never names the competitor, a page that does not say what people searched, the button below the fold, slow on a phone, Google rating the landing page below average. Reading only; nothing reaches Google. | ads.view | فقط می‌خواند |
ads_scorecard | For one connected ad account: every automatic change of the last 30 days with its stated expected effect (metric, direction, size and a 14-day window), the measured result 14 days on (first-party outcomes where we have them, else the ad network's own conversions; spend in micros of the account currency), the verdict (pending, better, same, worse, no_data, gone) and its Undo: proposed (one click on the findings list), undone (automatic changes on), held (the owner's decision, a learning freeze, the account's standing), expired. Reading only; nothing reaches the ad network. | ads.view | فقط می‌خواند |
ads_rule_preview | For one connected Google Ads account, replay a rule (if a metric over a window crosses a threshold, then an action) over the last N days (1-90) of the account's real stored figures and say what it WOULD have done: each day and campaign it would have acted on, with the reading; campaigns the owner locked or that are learning after a bid-strategy switch are listed as held. Writes nothing and calls no network. Answered from the daily audit's figures. | ads.view | فقط می‌خواند |
ads_rule_create | Create a rule (if a metric over a window crosses a threshold, then an action) on one connected Google Ads account; it runs once a day on its own schedule. A rule made here is ALWAYS approve-first: each change it proposes waits in the account's approval queue for a person, then passes every guard (kill switches, good standing, spend ceilings, owner-locked campaigns, the 14-day bid-strategy freeze) and keeps a 30-day undo. A campaign it acted on is left alone for cooldown_days. Preview it first, which writes nothing. | ads.manage | چیزها را تغییر می‌دهد |
ads_reviews | Every scheduled review of a connected ad account (AUTOREVIEW1): what it judges (a campaign's results since a day, a change's effect, an experiment's end, a Quality Score re-read, or clicks-to-results), the campaigns or change it covers, its due day, its status (scheduled, due, decided, cancelled) and, once due, the measured verdict (working, worse, not_working, too_early, unchanged, no_data), the recommended decision and the figures it rests on (money in integer micros). Also the campaigns and the changes of the last 30 days a new review can cover. It changes nothing. | ads.view | فقط می‌خواند |
ads_review_create | Schedule a review on one connected ad account: subject (results, change, experiment, quality, funnel), a short title, the due day (due_on YYYY-MM-DD, or days from today), optionally the day it measures from, the campaign ids it covers (none = all), the change id it reviews (subject change), and the decisions it offers (keep, pause, revert, extend). On its due day the platform measures it and writes the verdict; the decision is a person's one click. Creating it changes nothing in the ad account. | ads.manage | چیزها را تغییر می‌دهد |
ads_review_decide | Take one of the decisions a DUE review offers: keep (records it), extend (7 more days, then judged again), pause (pauses its campaigns in the live account, each through the approve-first queue as an approved change with a 30-day Undo) or revert (starts the reviewed change's Undo). The decision itself can be put back within 30 days from the dashboard. | ads.manage | چیزها را تغییر می‌دهد |