# Introduction > What Roasby is, who it is for, and how it keeps your ad accounts safe. Roasby (say *ROHZ-bee*) is your ROAS buddy. It lets you manage your Google Ads, Microsoft Ads and ChatGPT Ads by talking to the AI you already use, such as Claude, ChatGPT, Codex or Cursor. The work happens through your AI assistant: research, edits to bids, settings, ads and keywords, and new campaigns. The web dashboard is for: - watching your results; - pausing and enabling; - setting daily budgets; - approving recommendations; - reverting changes; - setting your safety guardrails. **Ask your AI** prompts on the [dashboard](/docs/dashboard), alerts, recommendations and search terms pages start a chat with your assistant in one click. ## What you can do - **Ask about performance** across all your ad accounts in plain language, or see it on the [dashboard](/docs/dashboard). - **Review your campaigns**, ad groups, ads and keywords, with impression share and policy findings, on the [Campaigns](/docs/campaigns) page. - **Change how campaigns bid**, and which conversion goals they bid on, through your assistant (see [Bidding and goals](/docs/bidding-and-goals)). - **Edit your campaigns** (bids, settings, ad text and keywords) by asking your assistant (see [Editing campaigns](/docs/editing-campaigns)). It shows you every change before it makes it. - **Create campaigns through your AI assistant** (see [Creating campaigns](/docs/creating-campaigns)). They always start paused, so nothing goes live by accident. - **Add sitelinks, callouts and other assets** through your assistant (see [Assets](/docs/assets)). - **Research keywords** with search volumes and bid estimates (see [Keyword research](/docs/keyword-research)). - **Find wasted spend** and cut it, with your approval (see [Search terms](/docs/search-terms)). - **Approve recommendations** Roasby makes from your results (see [Recommendations](/docs/recommendations)). - **Get alerts** for spend spikes, cost per conversion jumps and disapproved ads (see [Alerts](/docs/alerts)). - **Read the weekly report** every Monday (see [Weekly report](/docs/weekly-report)). - **See and revert every change** in the [change log](/docs/change-log). ## Try asking Once your assistant is connected, try: - *"How did my ads do last week across all platforms, and what changed most?"* - *"Find the search terms that wasted money last month and suggest negative keywords."* - *"Which of my search campaigns are limited by budget?"* - *"Create a paused search campaign for our new hiking boots, with keyword ideas for the US."* ## How it works 1. **Create your Roasby account.** Continue with Google, or enter your email on the [sign-in page](/login). New accounts add a name and a password and accept the terms. Your personal workspace is ready right away. 2. **Set your safety defaults.** Before your first dashboard, Roasby asks how far one change may move a budget or a bid (50% is filled in), and which emails you want. Keep the values or change them, or choose **Set later** (see [safety defaults](/docs/safety-model#safety-defaults-for-new-ad-accounts)). 3. **Connect your AI assistant** (see [Connect your AI](/docs/connect-your-ai)). 4. **Connect your ad accounts** (see [Ad accounts](/docs/ad-accounts)), then set each one's max daily budget in its currency (and, if you want, a max bid). 5. **Ask your assistant.** It reads freely, and asks you before it changes anything (see the [safety model](/docs/safety-model)). ## Paused by default Everything your assistant creates through Roasby starts **paused**: campaigns, ad groups, ads and keywords. Nothing runs or spends until you enable it, or your assistant does after you confirm. Roasby never deletes anything. See [Everything new starts paused](/docs/safety-model#everything-new-starts-paused). ## Built for AI assistants Every docs page is also available as Markdown: add `.md` to the address, or use **Copy for agents** at the top of the page. The whole documentation is at [/llms.txt](/llms.txt) and [/llms-full.txt](/llms-full.txt). Your assistant can also read these docs through Roasby itself: `search_docs` finds the pages about a question, even with a typo, and `get_doc` reads one page. To search the docs yourself, select **Search docs** at the top of the page list, or press **Ctrl K** (**⌘K** on a Mac). The search forgives typos, so "mcp tols" still finds the MCP tool reference. --- # Connect your AI > Add Roasby to Claude, Claude Code, ChatGPT, Codex, Cursor or VS Code with one address, then sign in and approve the connection. Add Roasby to your assistant with the address `https://roasby.com/mcp` (an MCP server). Your assistant then asks you to sign in to Roasby and approve the connection. The approval screen shows which Roasby account you are signed in to and where it sends you back to. It also lists what the assistant will be able to do: - **read** your ad accounts, campaigns, search terms and performance; - **make changes** (pause, enable, budgets, bids and bidding, campaign settings, ad text, keywords, negative keywords, assets and conversion goals) only after a preview you confirm; - **create** new campaigns, ad groups, ads and keywords, always paused. You can disconnect at any time. **Copy connector URL** in the **Ask your AI** panel (the button in the bottom corner of every workspace page, see the [dashboard](/docs/dashboard#ask-your-ai)) copies the address for you. Once you are connected, the same panel opens a chat with your assistant in one click. ## Claude (web, desktop and mobile) 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Enter the URL `https://roasby.com/mcp` and confirm. 3. Sign in to Roasby and approve access. ## Claude Code ```bash claude mcp add --transport http roasby https://roasby.com/mcp ``` Then run `/mcp` in Claude Code and choose **Authenticate** for Roasby. ## ChatGPT Open **Settings → Apps & Connectors**, add a connector with the URL `https://roasby.com/mcp`, then sign in to Roasby and approve access. ## Codex Add Roasby to `~/.codex/config.toml`: ```toml [mcp_servers.roasby] url = "https://roasby.com/mcp" ``` ## Cursor Add Roasby to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global): ```json { "mcpServers": { "roasby": { "url": "https://roasby.com/mcp" } } } ``` ## VS Code Add Roasby to `.vscode/mcp.json`: ```json { "servers": { "roasby": { "type": "http", "url": "https://roasby.com/mcp" } } } ``` ## Check that it works Ask your assistant: *"Which Roasby workspace am I in?"* It should call `get_current_workspace` and answer with your workspace name. To see who else is in it, ask *"Who is in my Roasby workspace?"* (`get_workspace_members`). ## Work in more than one workspace One connection reaches every workspace you belong to. See [Workspaces](/docs/workspaces#work-in-another-workspace-through-your-assistant) for how your assistant picks one. ## Disconnect an assistant Open **AI connections** (under **Manage** in the sidebar). It lists every assistant that can still reach your Roasby account and when each last used it. Choose **Disconnect** to end its access at once. To use it again, add Roasby to the assistant again and approve the connection. Removing Roasby inside your AI app doesn't tell Roasby, so the assistant stays on this page until its access runs out. An assistant that hasn't used Roasby for 14 days shows **Not used recently**; if you removed it, choose **Disconnect** here too. Disconnecting only affects your own account. Other people in your workspace keep their own connections. Disconnecting is done on this page only, not through an assistant. ## Install the Roasby plugin The Roasby plugin adds Roasby's connection and its skills. Its source is the public [Roasby/roasby](https://github.com/Roasby/roasby) repository. In Claude Code, add its marketplace, then install the plugin: ``` /plugin marketplace add Roasby/roasby /plugin install roasby@roasby ``` Then run `/mcp` and choose **Authenticate** for Roasby, as above. In Codex: ``` codex plugin marketplace add Roasby/roasby codex plugin add roasby@roasby ``` Any assistant that reads Agent Skills can install the skills alone. They need the Roasby connection too, so add Roasby as above first: ``` npx skills add Roasby/roasby ``` The `working-with-roasby` skill teaches your assistant how to work with your ads safely: - start with `get_current_workspace`, to know which workspace it acts in and whether you may change its ads; - read freely, and find the IDs it needs with the read tools; - preview every change, show it to you and wait for your yes before it makes it; - tell you a refused preview's reason instead of trying again; - explain the steps only a person can do, and never say it did them. Four more skills walk your assistant through common jobs: `roasby-wasted-spend-audit` (find and cut wasted spend), `roasby-weekly-review` (a review of the week across platforms), `roasby-launch-search-campaign` (plan and create a campaign, paused) and `roasby-budget-and-bid-check` (where budget or bids would help). The plugin is waiting to be listed in the Claude, OpenAI and Cursor directories. Until it is, install it as above, or add Roasby as a connector or MCP server: you get the same tools. ## Limitations - Your assistant can do only what Roasby's tools offer. Connecting ad platforms, billing, account settings and AI connections stay on the web. - Your assistant is told to ask you before every change, but the preview can't prove you agreed: read your AI app's prompt before you approve a change. - The plugin needs a Roasby account with at least one connected ad account. - A connection reaches every workspace you belong to. You can't limit it to some of them: to keep an assistant out of a workspace, leave that workspace or disconnect the assistant. See every limit by platform on [Limitations](/docs/limitations). --- # Safety model > The rules that keep your AI assistant inside your limits on real ad accounts. Roasby lets AI assistants act on real ad accounts, so it is designed around one idea: **your AI can analyse freely, but it changes things only through previews and guardrails, and it is built to ask for your approval.** These rules apply in every workspace. ## Everything new starts paused Nothing Roasby creates runs or spends until you enable it, or your assistant does with your explicit confirmation. ### New campaigns - A campaign your AI assistant creates through Roasby is always created **paused**. Its ad groups, keywords and ads are created ready under it. - The whole campaign is one change with one confirmation, created all at once or not at all. - If an ad platform makes only part of it, it stays paused, and Roasby doesn't enable it until its next sync shows every part of it. ### New keywords, ad groups and ads - **Keywords** your assistant adds to an ad group you already have are created **paused** too, even when the ad group is running. Your assistant offers to enable exactly those keywords with one more confirmation. - A new keyword's own bid must be within the ad account's max bid when it has one. A keyword whose bid is above the max bid (for example after you lowered it) is not enabled until its bid is within it. - **Ad groups** your assistant adds to a campaign you already have are created **paused** as well, with their keywords and ads ready under them. An ad group the ad platform made only partly is not enabled by Roasby until its next sync shows an ad in it. - Any ad group (new or not) whose default bid, or the own bid of an enabled keyword in it, is above the max bid is not enabled until the bids are within it. - When you change a keyword's text (or its match type on Google Ads, which can't change it in place), the new keyword is added **paused** and the old one paused, so neither runs until you enable the new one. - **Responsive search ads** your assistant adds to an ad group you already have are created **paused** too. Roasby doesn't enable a responsive search ad in an ad group that already runs the 3 the ad platforms allow. - Roasby never sends an ad twice: if the ad platform doesn't answer, Roasby doesn't try again, and its next sync shows whether the ad was made (paused). ### Assets Sitelinks, callouts and other assets are linked **paused** on Google Ads. Microsoft Ads can't pause an asset link, so there Roasby links new assets only to a paused campaign or ad group, where they show nothing until you enable it, and never to a whole account. ### Reverts When you revert a change yourself, these checks don't hold you back: a revert puts back what you had. Your AI assistant's reverts get no such exemption. ## Nothing is ever deleted Roasby never deletes or archives (removes) anything, because a removed item cannot come back on most ad platforms. Items that are already archived are read-only. Through Roasby you can pause, enable, change budgets and bids, edit ad text in place, create (paused) and add negative keywords, and most of those changes can be reverted. A few things are taken away, and only in ways you can undo: - Reverting added negative keywords removes exactly the ones that change added, never ones that were there before. - Editing a search campaign's countries or ad schedule replaces those targets: the ones no longer wanted are taken away and new ones added. The change log keeps the old ones, so reverting the change puts them back. - Assets are never removed. On Microsoft Ads, which can't pause an asset link, pausing a link takes the link away (never the asset), and enabling it or reverting the pause links it again. ## Budget and bid guardrails Each ad account has these guardrails, set by workspace owners and admins under **Ad accounts → Guardrails**: - **Max daily budget per campaign**, in the account's currency. Empty means no cap. - **Max budget change per step**, in percent of the current budget. New accounts start at your workspace's default (50% unless you changed it): at 50%, a $20 budget can rise to $30 in one change. A cut is never held to it: lowering spend takes one change. - **Max bid**, in the account's currency, for any ad group or keyword. Empty means no cap. - **Max bid change per step**, in percent of the current bid. New accounts start at your workspace's default (50% unless you changed it): at 50%, a $2.00 bid can rise to $3.00 in one change, and a cut takes one change. A keyword without its own bid is measured against its ad group's bid. - **Max target CPA** (optional), in the account's currency, for a campaign's or ad group's target CPA. Empty means no cap. - **Min target ROAS** (optional), in percent, for a campaign's target ROAS. Empty means no floor. A new campaign needs a max daily budget on its ad account, and its budget must stay within it. - Any new budget outside the guardrails is refused with a clear reason, whoever sets it (a person's revert skips only the max change per step). - Enabling is checked too: a campaign whose daily budget is above the max daily budget stays off until you lower the budget or raise the cap. A campaign that was only partly created stays off until a sync shows an ad in it. Reverting your own pause is the one exception. - When you lower the cap below a campaign's current budget, that budget can be brought down to the new cap, or below it, in one step. Only people can change guardrails, in Roasby itself. Your AI assistant can read them (`list_ad_accounts`, and the workspace's safety defaults with `get_current_workspace`) but never loosen them. ### Bid adjustments A campaign's device and ad schedule bid adjustments raise or lower every bid, so they keep the **max bid change per step** too. Roasby measures them as multipliers (+20% is 1.2, -50% is 0.5) in whole hundredths and checks every pair of a device and a quarter hour of the week that shows ads after the change, with whole numbers only, so no rounding lets one slip past: - **Each pair** may rise at most one step: the device multiplier times the hour's multiplier after the change must be at most the same product before × (1 + max change). At 50%, with mobile and Mondays 9:00–17:00 both at +0%, mobile may go to +50%, or Mondays to +50%, or mobile to +20% and Mondays to +25% (1.2 × 1.25 = 1.5), but not both to +50% (2.25). - **What showed no ads before** counts as no adjustment (1.0) and gets no rise in that step: a device at -100% may come back at 0% at most (times the hours as they were), and hours a schedule left out, where no ads ran, may be added at 0% at most (times the device as it was). A rise past that is the next step. - **No schedule** means every hour at 0%. A slot moved to other times is checked hour by hour the same way, and so is taking the schedule away: hours that ran lower before, or ran no ads, rise to 0%. - Lowering an adjustment and switching a device off are always allowed. A rise past a step is refused, naming each device and time slot (for example "Mobile in Monday 09:00–17:00: +125% asked, at most +50% in one step"). - If you ask your assistant to limit it to the guardrails, Roasby lowers each adjustment to what its pairs allow, and then every rise by the same share until all pairs fit. The preview lists them, with the values asked for as the next step. - When taking a schedule away would raise bids too far, the schedule stays in that step, its slots raised as far as allowed, and taking it away is the next step. - An AI assistant's revert of a lowered adjustment is held to the same rule; your own revert on the web restores what you had. ### Bidding targets Bidding targets have their own guardrails, and the bid change per step: - A target impression share's or maximize clicks' **max cost per click** stays within the account's **max bid** when one is set. - A **target CPA** is a cost per conversion, usually many times a cost per click, so it stays within the account's **max target CPA** when one is set, never within the max bid. For example, a max bid of EGP 120 doesn't hold a target CPA of EGP 1,500. - A **target ROAS** stays at or above the account's **min target ROAS** when one is set. - In one step, a target CPA or a max cost per click rises at most the **max bid change**. - A **target ROAS** falls at most that much in one step, because a lower ROAS spends more. - A first target has no step, and bidding without a target spends up to the daily budget, within its guardrails. - Maximize conversions and conversion value without goals that record conversions are allowed with a warning: the tracking is yours to fix in the ad platform. - Roasby changes only bidding it could put back exactly, and a revert restores the strategy and every target. - While a campaign bids automatically, Roasby refuses changes to its keyword and ad group bids. See [Bidding and goals](/docs/bidding-and-goals). ### Safety defaults for new ad accounts Each workspace has two **safety defaults**: the max budget change per step and the max bid change per step that every ad account you connect starts with. They need no currency, so you set them once for the workspace: - **At sign-up**, before the workspace's pages, Roasby walks owners and admins of a new workspace through them, with 50% filled in and an example of what each value allows. If an invitation to another workspace is waiting for you, you see it first, and a note on the dashboard links to this setup. The same screen asks whether members may change ads (in shared workspaces) and which emails you want: the weekly report and alerts. Choose **Save and continue**, or **Set later** to keep the values filled in. - **Later**, owners and admins change them under **Workspace settings → Safety defaults**. Ad accounts you already connected keep their own guardrails; change those under **Ad accounts → Guardrails**. The money caps need the account's currency, so you set them when you connect it: right after connecting, Roasby opens each account new to the workspace (not one you reconnect) with its **max daily budget** and **max bid**, with the change limits filled in from your safety defaults. Save them, or choose **Set later** for that account. Until an account has a max daily budget, your AI assistant cannot create campaigns in it. ## Limits on how fast things change - An ad account accepts at most **60 changes in any 60 minutes**, which stops a runaway assistant. A [batch](#batches-many-items-in-one-change) counts as one change. Reverting a change yourself is never blocked by this limit and does not count toward it. - One change at a time per item: a second change to the same budget or status is refused until the first one is applied, so try again a moment later. - Where an ad platform limits how often one item may change, Roasby holds you to the same limit with a clear message, instead of letting the platform fail the change. ## A change log you can revert Every change is recorded in the **Change log** (in the sidebar) with who or what made it (you, a teammate, an AI assistant, or Roasby itself), the value before and the value after. - A change is **Pending** until the ad platform confirms it, then **Applied**, or **Failed** with the reason. - An applied status, budget or bid change shows in Roasby at once. After a new campaign, Roasby usually syncs that ad account within a few minutes, so everything the platform made shows (this doesn't use your **Sync now** allowance). Anyone who may change ads (see below) can **Revert** an applied change with one click: - Reverting a new campaign pauses it. - Reverting negative keywords takes away the ones the change added (and reverting that adds them again). - Reverting an ad text edit writes the ad's old text back (your assistant may do that too: ad text spends no money). - For a status or budget, the revert is a new change in the log that puts the value before back. It is checked by the same guardrails, except the max change per step, since it restores a value the item already had. A revert by an AI assistant is held to the max change too. A change can be reverted once (a revert the ad platform refused can be tried again), and only while the item still has the value it set: if it changed again since, revert the newer change first. Your assistant can read the log with `list_ad_changes`, for example *"What did you change in my Google Ads account today?"*. See [Change log](/docs/change-log) for every status, what each revert does and what can't be reverted. ## Batches: many items in one change You can pause or enable many campaigns, ad groups, ads and keywords of one ad account together, on the [Campaigns page](/docs/campaigns#changing-many-items-at-once) or through your assistant. Your assistant can also [change the bids](/docs/bidding-and-goals#changing-bids-through-your-ai-assistant) of many ad groups and keywords, or edit many ads or keywords, as one batch. A batch works like this: - **One preview.** Roasby checks every item with the same rules as a single change, and shows how many items will change, which are refused and why. Refused items stay as they are; confirming changes only the items that pass. - **One confirmation.** Your assistant gets one confirmation token for the whole batch, and only for those items with the values they have now. If any item changes before you confirm, the batch is previewed again. - **A result for every item.** Each item is applied or fails on its own, with the ad platform's reason. The change log shows the batch as one entry (**Applied**, **Partly applied** or **Failed**); open it to see each item. - **The same guardrails for every bid.** Each bid in a batch is checked like one bid change: the max bid, the max bid change per step, and only campaigns that use your bids. If you ask Roasby to limit bids to the guardrails, a bid beyond them moves only as far as they allow, and is marked as limited; it never goes past them. Only people change the guardrails, on the **Ad accounts** page. - **One revert.** **Revert batch** puts back the value before of every item the batch applied, as a new batch (for keywords, ad groups or ads it added, it pauses them). You can still revert a single item of a batch on its own. - **One change toward your limits.** A batch counts as one change toward your workspace's monthly changes and the hourly limit of the ad account. Your workspace can change only so many items in one batch (see [Billing](/docs/billing); each ad group, keyword, negative keyword and ad a batch adds counts as one, and so does every part of a [new campaign](/docs/creating-campaigns#the-whole-campaign-at-once), which is one change), and on Google Ads a batch must also fit Roasby's shared daily Google Ads capacity. ## Who can change ads Workspace **owners and admins** can change ads: pause, enable and set campaign budgets on the [Campaigns page](/docs/campaigns), revert changes in the change log, and make every change Roasby offers through their AI assistant. **Members** can read everything but change nothing, unless an owner or admin turns on **Allow members to change ads** in **Workspace settings** (under **Manage** in the sidebar). Every switch of that setting is recorded. Guardrails, ad platform connections and the setting itself always stay with owners and admins. An AI assistant acts with exactly the rights of the person who connected it, and only people can change who may change ads. See [Workspaces](/docs/workspaces#roles) for roles and invitations. ## Your assistant previews every change Reading reports and finding problems needs no confirmation. Every change takes two steps: 1. **Preview.** Your assistant calls a `preview_*` tool (for example `preview_update_campaign_budget`). Roasby checks the change against all the rules above without changing anything, and tells the assistant the value before and after, the account's guardrails, and either why the change would be refused or a **confirmation token**. 2. **Confirm and apply.** Your assistant is told to show you the change and ask you to confirm before it calls the matching tool (for example `update_campaign_budget`) with the token, and Roasby checks everything again. The token works **once**, for **10 minutes**, and only for that exact change, by you and that assistant. If anything differs (a different amount, another item, or the item changed in the meantime), the change is refused and your assistant previews it again. Many AI apps also ask you before they run a tool that changes something: read that prompt before you approve it. ### Steps only a person can do Some steps are for a person, in Roasby or in an ad platform: for example setting or raising a guardrail, reconnecting an ad account, or declaring EU political ads for a whole Google Ads account. A preview or a result lists them in `user_actions`: what to do, why, where, and a link when there is one. - Your assistant is told to explain each step to you in plain words, with its place and link, and never to say or suggest that it did the step itself. - A step marked `optional` is a choice, not a requirement. Your assistant first offers what it can do within the rules (a smaller step, a value within the cap). - Where a Roasby tool does the same step (making an ad account active, writing to support), your assistant offers it through the usual preview and confirmation. ## Limitations - The confirmation token proves your assistant previewed the change, not that you agreed. Read your AI app's own prompt before you approve a change. - Your assistant can't change guardrails, safety defaults or who may change ads. When only you can do something, it tells you what, why and where. - A change can be reverted once, and only while the item still has the value it set. On an account that is over the limit, only a person can revert, on the web; an account set read-only by support refuses reverts too. - A batch changes one ad account at a time, and has at most as many items as your workspace allows in one batch. - A bidding target moves at most one max bid change per step (a target CPA or max cost per click up, a target ROAS down), and stays within the guardrails that are set. - A bid adjustment (device or ad schedule) rises at most one max bid change per step, also when a device and a time slot multiply; a larger rise takes several steps. - Roasby never deletes anything, so a mistake is fixed by pausing or reverting, never by removing. See every limit by platform on [Limitations](/docs/limitations). --- # Dashboard > See spend and results across Google Ads, Microsoft Ads and ChatGPT Ads in one place, for all accounts or one account or campaign. The **Dashboard** is the first page of your workspace: performance across every ad platform, your top campaigns, the latest changes and your connected ad accounts, at a glance. The work itself (research, edits, new campaigns) happens in your AI assistant, and the **Ask your AI** button helps you start it from any page. ## Getting started A new workspace shows a short checklist, **Your workspace is ready**, with the steps left to do: **Connect an ad account** and **Connect your AI assistant**. Each step gets a check mark when it is done. The checklist goes away once both are done; until then you can collapse it with the arrow next to the progress. ## Ask your AI The **Ask your AI** button sits in the bottom corner of every workspace page. It opens a small panel: - Type any question about your ads, or pick one of the prompts under **Try**. The prompts fit the page you are on: on the dashboard they are **Weekly performance**, **Wasted spend**, **Recommendations** and **Keyword ideas**; on [Search terms](/docs/search-terms), [Campaigns](/docs/campaigns), [Alerts](/docs/alerts), [Recommendations](/docs/recommendations), the [change log](/docs/change-log) and [Ad accounts](/docs/ad-accounts) they match that page. - A picked prompt fills the box, so you can change it before you send it. - **Ask Claude** or **Ask ChatGPT** opens a new chat with your question typed in; **Copy** copies it for another assistant. - **Copy connector URL** copies Roasby's address to add to your assistant, and **How to connect** opens the [Connect your AI](/docs/connect-your-ai) guide. Your own question is sent as *Use Roasby in my workspace "…": your question*, so the assistant works in the right workspace. The ready prompts name only your workspace; your assistant reads everything else through Roasby, and shows you any change before it makes it. ## Filters At the top, next to the workspace name, you choose what the dashboard shows: - **Ad account**: every account, or one. Picking an account also narrows the campaign choices to its campaigns. - **Campaign**: every campaign, or one (archived campaigns are not offered). Picking a campaign also picks its account. - **7 days**, **30 days** or **90 days**: the period. The dates show under the title. The title becomes the account or campaign you picked. The filters change the performance figures and the top campaigns; the recent changes and the ad accounts always cover the whole workspace. Your choices stay in the page address, so you can bookmark or share a filtered view with your teammates. ## Needs attention When there are open [recommendations](/docs/recommendations), open [anomaly alerts](/docs/alerts) or safety defaults still to set, a **Needs attention** row under the filters says so: a blue dot for recommendations, an amber one for alerts. Each item links to where you act on it; the safety defaults item also has **Set later**. ## Performance A period always ends **yesterday**, so you only compare complete days. Each ad account counts days in its own time zone, so the period ends on the last day every account has finished. - **Spend**, **Conversion value**, **ROAS** (conversion value divided by spend), **Conversions**, **Clicks** and **Impressions**, added up across every connected platform (or the account or campaign you picked). A ChatGPT Ads account needs purchase tracking to report conversion value. Until its first attributed sale it shows n/a for value and ROAS, and its spend is left out of the combined ROAS. A note under the figures says how much was left out. - Under each figure, the change against the same number of days just before. Green is good news (more conversions, a higher ROAS), red is bad news, blue is spend (more can mean growth, less can mean savings), grey means no change. - A daily chart of spend and conversion value. - The same figures by platform and by ad account, largest spend first. **Currencies are never converted.** If your ad accounts use different currencies, the dashboard shows one currency at a time, with a switch at the top. The numbers are as fresh as each account's last sync (see [Syncing](/docs/ad-accounts#syncing)); **Sync now** on the **Ad accounts** page updates an account right away. Read-only ad accounts still count with the history they already have; a disconnected account is removed from every figure. A comparison needs history for twice the period (60 days for 30 days), so it is left out until there is enough. ## Top campaigns and recent changes - **Top campaigns** lists your top campaigns for the same period, largest spend first, with their platform, status, account, spend, conversions and ROAS. **Active** shows only the campaigns that are running; **All** adds the paused ones and the archived ones that spent money in the period. **View all** opens the [Campaigns](/docs/campaigns) page for the same period. - **Recent changes** shows the latest changes made by you, your teammates or your AI assistant, with who made them, when, and whether they applied. **Change log** opens the full [change log](/docs/change-log), where you can revert them. ## Ad accounts **Ad accounts** shows the workspace's current accounts with their platform, last sync and status. **View all** opens the [Ad accounts](/docs/ad-accounts) page, which also lists closed accounts. ## Ask your AI assistant Your assistant reads the same numbers with `get_performance_summary` (for every account, or one account or campaign with `ad_account_id` or `campaign_id`), and the campaigns with `get_campaign_performance`. Try: - *"How did my ads do in the last 30 days compared with the month before?"* - *"How did my Google Ads account do last week compared with the week before?"* - *"Which campaigns spent the most this month, and how many conversions did they bring?"* ## Limitations - The numbers are as fresh as each account's last sync, and a period always ends yesterday. - Currencies are never converted, so each currency has its own figures. - A ChatGPT Ads account shows conversion value and ROAS only with purchase tracking. See every limit by platform on [Limitations](/docs/limitations). --- # Campaigns > Browse campaigns, ad groups, ads and keywords with Quality Score, impression share and policy review, and pause, enable or set daily budgets. The **Campaigns** page is for watching your campaigns, pausing and enabling them, and setting daily budgets. Everything else you do by asking your AI assistant (see [Connect your AI](/docs/connect-your-ai)). Open **Campaigns** in the sidebar of your workspace to see the campaigns of every connected ad account, or **Campaigns** on one account on the **Ad accounts** page to see only its campaigns. Your assistant handles the rest: - bids, bidding and conversion goals: see [Bidding and conversion goals](/docs/bidding-and-goals); - campaign settings, ad text, keywords and negative keywords, and new ad groups, ads and keywords: see [Edit campaigns with your AI](/docs/editing-campaigns); - new campaigns: see [Create campaigns with your AI](/docs/creating-campaigns); - sitelinks and other assets: see [Sitelinks, callouts and other assets](/docs/assets). To exclude searches as negative keywords, use the [Search terms](/docs/search-terms) page. ## Finding your way - **Campaigns** is a table of every campaign with its platform's logo, its ad account, status, daily budget, and spend, conversions and ROAS for the chosen period (**7 days**, **30 days** or **90 days**). ROAS shows n/a for ad accounts that don't report conversion value. - **Status** shows only the **Active** items. Pick **Paused**, **Archived** or **All statuses** to see the others. It applies to the list you are on; opening a campaign or ad group shows its active items again. New items your AI assistant creates start paused, so pick **Paused** to find them. - **Ad account** shows the campaigns of one account. **Campaign** opens one campaign's ad groups. - Select a campaign's name to open its ad groups, and an ad group's name to open its ads, with a switch to its keywords (and their match types). - The keywords show what the ad platform reports about each one: see [Quality Score and first page bid](#quality-score-and-first-page-bid). - Search campaigns and their ad groups show their impression share: see [Impression share](#impression-share). - Ads and keywords the ad platform disapproved, limited or is still reviewing have a badge: see [Policy review](#policy-review). - Ad groups and keywords show their **Max bid**. A keyword without its own bid shows **Uses ad group bid**. - The actions of each row are icon buttons (hover or focus one for its name): **Budget** (campaigns) and **Pause** or **Enable**. - **Search terms**, on the list of campaigns and of a campaign's ad groups, opens the [Search terms](/docs/search-terms) page for that ad account or campaign. - An ad account, campaign or ad group you open also lists its [assets](/docs/assets) under its table. The links at the top take you back up. A **Change pending** badge means a change to that item is on its way to the ad platform. Another change of the same kind (status, budget, bid or settings) is refused until it is done. The page checks again every few seconds and shows the new value once the ad platform has applied it. ## Quality Score and first page bid The keywords of an ad group have two more columns: - **Quality Score**: the ad platform's score from 1 to 10. Hover over it, focus it or tap it to see: - its three parts (expected click-through rate, ad relevance and landing page experience), each below average, average or above average; - the top of page and first position bid estimates; - the platform's reasons, and when Roasby last read them. - **First page bid**: the bid the platform estimates your ad needs to show on the first page of results, in the ad account's currency. Under a keyword's name you may see **Below first page bid** (with the estimate) or **Rarely shown (low search volume)**: these come from the ad platform. Its policy review has a badge of its own: see [Policy review](#policy-review). Roasby never makes these numbers up. When the platform gives none, the column says why: - **Not enough data yet**: the keyword has had too few searches for a score or an estimate. New and quiet keywords often show this. - **Not offered under automated bidding**: the campaign's bidding sets each bid itself, so the platform gives no bid estimates. - **Not reported yet**: Roasby hasn't read the campaign's bidding yet; it shows after the next sync. The details of a keyword without a score still show what the platform reported, such as the other estimates and its reasons. To find the keywords to work on, choose **Quality Score up to 3**, **5** or **7** (keywords without a score are left out) or **Below first page bid** above the list. The values are as of the ad account's last sync. To raise keywords to their first page bid, ask your assistant: see [Changing bids](/docs/bidding-and-goals#changing-bids-through-your-ai-assistant). ## Impression share Campaigns and ad groups have an **Impression share** column for the chosen period: the share of the searches your ads could have shown on that they did show on. Under it you see what the rest was lost to: - **Lost to rank**: your ad didn't rank high enough to show, because of its bid, its quality or the competition. Raising the bid or improving the ad and its keywords helps. - **Lost to budget**: the daily budget ran out before the day was over. A higher budget helps, if the campaign converts. A budget belongs to the campaign, so Google Ads reports this for campaigns only: its ad groups show only what they lost to rank. Hover over it, focus it or tap it to see both, plus the **top of page** share (above the search results) and the **absolute top** share (the very first position). Roasby never shows a number the platform doesn't give: - **<10%** and **>90%**: Google Ads reports an impression share below 10% and a lost share above 90% only as that bound, so Roasby shows the bound. - **≤45%** or **≥12%**: some days of the period were only reported as a bound, so the period's share is at most (or at least) that. **~30%** means bounds went both ways, so it is about that. - Microsoft Ads may mark a value with < or >; Roasby keeps it as a bound the same way. - **Not enough data**: the platform reported no share, for example on days without enough searches. A period's share counts each day by the searches it could have shown on, not as a plain average of the days. Display, shopping and other campaigns that don't run on search have no impression share (–). ## Policy review Google Ads and Microsoft Ads review every ad and keyword against their advertising policies. When one is not fully approved, a badge shows under its name: - **Disapproved**: it doesn't show at all. - **Limited**: it shows only in some countries, to some people, or for some searches. - **Under review**: the platform hasn't finished its review yet (usually within two days). - **Policy issue**: the ad is approved, but a headline or description of it was limited or refused. Select the badge to see each finding: - the policy, in plain words (or the platform's own name for a policy Roasby doesn't know yet); - whether it stops the ad or only limits it; - the headline or description it is about, when the platform says; - what the platform flagged: words, a website, a URL that doesn't work with its error; - the countries where it can't show; - what you can change, such as new wording or fixing the landing page. Microsoft Ads also says whether you can appeal, and Google Ads whether an appeal is open. To find them all, choose **With a policy issue** in the **Policy** menu above the ads or keywords of an ad group. It lists the disapproved and limited ones and those with a finding, not those only under review. Roasby never asks a platform for a review, an exception or an appeal. Instead: - change what the finding names (for example, ask your assistant to [add an ad](/docs/editing-campaigns#adding-responsive-search-ads-through-your-ai-assistant) with new wording, then pause the old one); - or request a review in the platform's own website: the **Google Ads web interface** or **Microsoft Ads web interface** link in the findings opens it. Findings are as of the ad account's last sync. ## Conversion goals Under each campaign's name, a small label says which conversion goals its bidding aims for: - **Account goals**: the ad account's goals (on Google Ads, its goals that bid; on Microsoft Ads, all of its conversion goals that count toward bidding). - **Campaign goals**: goals chosen for this campaign only. - **Custom goal: …**: a Google Ads custom goal with its own conversion actions. Select it to see what bidding aims for. It turns amber with a warning when something is wrong: - a goal it bids on has no enabled primary conversion action; - it still bids on a conversion action that was removed; - or none of its goals is used for bidding. Conversion actions are set up in the ad platform. Ask your AI assistant for every conversion action of an account and the campaigns with goals of their own: see [Conversions](/docs/conversions). Your AI assistant can change which goals a search campaign bids on; there is no web form for it. See [Changing conversion goals](/docs/bidding-and-goals#changing-conversion-goals-through-your-ai-assistant). ## Bidding Under each campaign's name, a small label also says how it bids, with its targets (for example **Maximize conversions, target CPA $45.00**). Select it to see whether your assistant can change it. An ad group with a target CPA of its own shows it under its name. Bids and bidding are changed only through your assistant: see [Bidding and conversion goals](/docs/bidding-and-goals). ## Pausing, enabling and budgets - **Pause** stops an enabled item; **Enable** resumes a paused one, which can start spending money again. - **Budget** sets a campaign's daily budget in the ad account's currency. Each change asks you to confirm. It follows the same rules as an AI assistant's (guardrails, limits, one change at a time; see the [safety model](/docs/safety-model)) and is added to the [change log](/docs/change-log), where you can revert it. The new status or budget shows once the ad platform confirms it, usually within a minute. Archived (removed) items are read-only. Budgets shared by several campaigns and lifetime budgets (a total for the campaign's dates) can't be changed in Roasby: change those in Google Ads, Microsoft Ads or ChatGPT Ads Manager. On ChatGPT Ads, you can pause and enable campaigns, ad groups and ads, and change the daily budget of a campaign. Your AI assistant can also change the max bid of an ad group, and creates new ChatGPT Ads campaigns as described in [Creating a ChatGPT Ads campaign](/docs/creating-campaigns#creating-a-chatgpt-ads-campaign). ## Amounts Daily budgets and bids use at most two decimals, or whole numbers in a currency without decimals, such as the yen. Roasby refuses a finer amount rather than rounding it, so the amount you confirm is the amount that is set. ## Changing many items at once Select rows with the box at the start of each one (the box in the header selects every row shown), then choose **Pause selected** or **Enable selected** in the bar that appears. You can mix campaigns, ad groups, ads and keywords, as long as they are in one ad account. Before anything changes, Roasby checks each item and shows you: - how many items will change, and how many are refused; - why items are refused, with how many each reason refused (for example, items already paused, or campaigns above the max daily budget of the ad account). Confirm, and the items that pass change together. Refused items stay as they are. The [change log](/docs/safety-model#batches-many-items-in-one-change) shows them as one entry that opens to each item and its result, and **Revert batch** puts every item back. A batch counts as one change toward your workspace's limits, and your workspace can change only so many items in one batch (see [Billing](/docs/billing)): split larger ones. ## Who can change ads Owners and admins can always change ads. Members can browse everything, and change ads only when an owner or admin turns on **Allow members to change ads** in the workspace settings. See [who can change ads](/docs/safety-model#who-can-change-ads). ## Campaign performance The [dashboard](/docs/dashboard) lists your campaigns for the chosen period, largest spend first, with spend, conversions, clicks and ROAS. ## Ask your AI assistant Your assistant finds the same items with `list_ad_entities`: - With `period`, it also gets each item's spend, conversions and ROAS, as on this page. - Each keyword comes with its Quality Score, bid estimates and statuses. `below_first_page_bid` or `max_quality_score` lists only the keywords below the first page bid or with a low score across an account. - Each ad comes with its approval status (approved, under review, disapproved, limited, or unknown when the platform reports none). Each ad or keyword the platform disapproved, limited or is reviewing also comes with its policy findings, and `policy_issues_only` lists only those with a policy issue. It reads campaign results with `get_campaign_performance`: each search campaign with its impression share and what it lost to rank and to budget (also in `list_ad_entities` for campaigns and ad groups), and each campaign with its `conversion_goals`. It checks conversion tracking with `list_conversion_actions` before it suggests how a campaign should bid. It changes things in two steps: a `preview_*` tool shows the change and the guardrails, you confirm, then a write tool applies it. - One item: `pause_entity`, `enable_entity` or `update_campaign_budget`. - Many items at once: `preview_pause_entities` or `preview_enable_entities` with their IDs (one preview of every item, one confirmation), then `pause_entities` or `enable_entities`. On the web you pause, enable and set daily budgets. Everything else is done only through your assistant: see [Bidding and conversion goals](/docs/bidding-and-goals), [Edit campaigns with your AI](/docs/editing-campaigns), [Create campaigns with your AI](/docs/creating-campaigns) and [Sitelinks, callouts and other assets](/docs/assets). Try: - *"Which of my search campaigns are limited by budget, and which by rank?"* - *"Why was my ad disapproved, and what should I change?"* - *"Which of my ads and keywords are disapproved or limited?"* - *"Which of my keywords are below the first page bid?"* - *"List the keywords with a Quality Score of 4 or less and tell me which part is weak"* - *"Pause every keyword in the Brand ad group that spent money without a conversion this month"* - *"Pause the campaigns in my Google Ads account that spent money without any conversions last week"* - *"Raise the Brand campaign budget by 10%"* ## Limitations - On this page you pause, enable and set daily budgets. Bids, campaign settings, ad text, keywords and negative keywords change only through your AI assistant (searches can also be excluded on the [Search terms](/docs/search-terms) page). - Shared budgets and lifetime budgets are changed in the ad platform itself. - A batch changes one ad account at a time, with only so many items in one batch; split larger ones. - Impression share: - search campaigns and their ad groups only; - Google Ads reports below 10% and lost above 90% only as bounds; - Microsoft Ads fills in the share later than other numbers (often about a day), so the last day may have none yet. - Quality Score: - the platform gives none for a keyword with too few searches, and no bid estimates under automated bidding; Roasby then says so instead of a number; - Microsoft Ads reports Quality Score and estimates only for keywords that had activity recently (a keyword without any keeps what Roasby read before); - Microsoft Ads has no **Below first page bid** status: compare the max bid with the first page bid yourself. - Policy review: - reviews, exceptions and appeals are only in the ad platform's own website; Roasby shows the findings and never requests them; - Microsoft Ads gives its reasons only for disapproved and limited ads and keywords; - Google Ads gives policy findings for ads, their headlines and descriptions, and keywords; sitelinks, callouts and other assets have no findings in Roasby; - ChatGPT Ads shows an ad's approval only (approved, under review or disapproved); - findings are as of the last sync. - Conversion actions are read only, every few hours, and changed in the ad platform. ChatGPT Ads campaigns show no conversion goals. - Roasby never deletes anything: pause instead. See every limit by platform on [Limitations](/docs/limitations). --- # Bidding and conversion goals > Ask your AI assistant to change max bids, bidding strategies and targets, and the conversion goals a search campaign bids on, within your guardrails. Your AI assistant changes max bids, how a search campaign bids, and which conversion goals it bids on. There is no web form for these: the [Campaigns](/docs/campaigns) page shows each campaign's bidding and goals, and your assistant shows you every change before it makes it. Every change here passes your ad account's guardrails (see the [safety model](/docs/safety-model)) and is added to the [change log](/docs/change-log), where you can revert it. ## Changing conversion goals through your AI assistant Your assistant can make a Google Ads or Microsoft Ads search campaign bid on the ad account's goals again, or on goals of its own. The [Campaigns](/docs/campaigns#conversion-goals) page shows which goals each campaign bids on. 1. It reads the campaign's goals with `get_campaign_performance` (on Google Ads each goal has a key) or the conversion goals with `list_conversion_actions` (Microsoft Ads). 2. It checks the change with `preview_update_conversion_goals`. 3. It makes it with `update_conversion_goals` once you confirm. Try *"Make the Brand campaign bid only on purchases"* or *"Let the Brand campaign use the account's conversion goals again"*. - The preview lists each chosen goal that is not recording conversions: bidding learns nothing from it. - Changing what bidding aims for restarts the learning period of automated bidding: results can swing for one to two weeks. - Roasby never creates a Google Ads custom goal. A revert puts back exactly what the campaign bid on before, including a custom goal. - A campaign changed in the ad platform since Roasby last read it is not changed: Roasby reads it again first. Conversion actions themselves are set up in the ad platform. Ask your assistant about them: see [Conversions](/docs/conversions). ## Changing bids through your AI assistant Ask your assistant to change the max bid of an ad group or a keyword, or of many at once. It shows you each bid before and after, and changes nothing until you confirm. - For one bid it uses `preview_update_bid`, then `update_bid`. - For many, `preview_update_bids`, then `update_bids`. Try *"Lower the bids of the ad groups in the Brand campaign by 15%"* or *"Raise every keyword of the Trail ad group to its first page bid, at most 2 dollars, within my guardrails"*. ### Many bids at once You can ask for many bids in three ways: - **One amount**: every item gets the same max bid, or each its own. - **A change in percent**: each bid goes up or down by a whole percent of its current bid, for example 20 or -15 (a keyword without its own bid starts from its ad group's). The new bid is rounded toward the current one, so it never moves further than you asked. - **The first page bid** (keywords only): each keyword goes up to the [first page bid](/docs/campaigns#quality-score-and-first-page-bid) the ad platform estimates, never above the highest bid you name. Keywords already at or above it stay as they are, and keywords without an estimate are left out, with the reason. Many bids change together as one **Bids changed** entry in the change log; **Revert batch** puts back each bid as it was (a keyword that had no bid of its own uses its ad group's again). ### Bid guardrails Every bid passes the same guardrails: - the account's max bid; - its max bid change per step; - only campaigns that use your bids. A rise larger than the max bid change per step, or past the max bid, is refused (a cut takes no steps), unless you ask your assistant to limit the bids to the guardrails. Such a bid then moves as far as the guardrails allow and is shown as limited, with the bid you asked for. For example, at a 50% step, raising EGP 27.00 to EGP 53.00 becomes EGP 40.50 now. - Once that is applied, ask for the bids you wanted again (your assistant gets them as the next step) to take the next step. - Don't repeat a percent, which would add up. - A bid stopped by the max bid goes no further until you raise the max bid. The guardrails are never passed, and only people change them, on the [Ad accounts](/docs/ad-accounts) page. ### Where bids can change Bids can change only where your bid is used: - Google Ads search campaigns with manual cost per click; - Microsoft Ads search campaigns with manual or enhanced cost per click; - ChatGPT Ads ad groups with a fixed max cost per click. Under automated bidding (such as maximize clicks or conversions) the platform sets the bids, and other campaign types use other bids, so Roasby refuses the change. Each ad platform also has its own bid limits, and a bid it refuses shows as failed in the change log. ## Changing bidding through your AI assistant Under each campaign's name on the [Campaigns](/docs/campaigns#bidding) page, a small label says how it bids, with its targets (for example **Maximize conversions, target CPA $45.00**). Select it to see whether your assistant can change it; an ad group with a target CPA of its own shows it under its name. Your assistant can change how a Google Ads or Microsoft Ads search campaign bids. It reads the bidding with `list_ad_entities`, checks the change with `preview_update_bidding`, and makes it with `update_bidding` once you confirm. Try *"Switch the Brand campaign to maximize conversions with a target CPA of 40 dollars"* or *"Raise the target ROAS of the Shoes campaign to 450%"*. ### Bidding strategies - **Manual cost per click**: your ad group and keyword bids set the price (Microsoft Ads uses enhanced cost per click for it). - **Maximize clicks**: the most clicks for the budget. - **Maximize conversions**, with an optional **target CPA** (the cost per conversion to aim for). - **Maximize conversion value**, with an optional **target ROAS** (the return on ad spend to aim for, in percent). - **Target impression share**: show on a share of searches, anywhere on the page, at the top or in the very first position, with a max cost per click. - **Ad group target CPA** (Google Ads, under maximize conversions): an ad group aims for its own target CPA instead of the campaign's. ### What keeps it safe - **Guardrails.** - Each guardrail below holds only once a person sets it under **Ad accounts → Guardrails**; the daily budget and its guardrail always bound the spend. - A max cost per click stays within the ad account's **max bid**. - A target CPA stays within the account's **max target CPA**. A target CPA is a cost per conversion, usually many times a cost per click, so it is never held to the max bid. - A target ROAS stays at or above the account's **min target ROAS**, when one is set. - In one step, a target CPA or max cost per click rises at most the **max bid change**, and a target ROAS falls at most that much (a lower target ROAS spends more). - A first target is held to those caps only. - Ask your assistant to limit a change to the guardrails, and it moves the target as far as they allow and tells you the next step. - **Conversions first.** Maximize conversions and maximize conversion value need conversion goals that record conversions (and, for value, conversions with a value). Otherwise the preview warns you, but doesn't refuse: the ad platform takes the bidding, and the tracking is yours to fix. Check [Conversions](/docs/conversions) first. - **Bids under automated bidding.** Automated bidding sets the bids itself, so your keyword and ad group bids are not used, Roasby shows no bid for them, and it refuses bid changes until the campaign bids manually again. It also ignores device bid adjustments (other than -100%), which the settings preview says. - **Goals of a new campaign.** Roasby reads a new search campaign's conversion goals a few minutes after it creates it, and **Sync now** reads them too, so you can set its goals, target CPA or target ROAS right away instead of hours later. - **Learning.** A bidding change starts a learning period: results can swing for one to two weeks. Bidding without a target spends up to the daily budget, within its guardrails. - **Only what Roasby can put back.** Roasby changes a campaign's own bidding only when it could set the bidding before back exactly. A portfolio strategy (shared with other campaigns), enhanced cost per click on Google Ads and some other strategies are changed in the ad platform. A revert puts back the strategy and every target the campaign had, with one exception: Microsoft Ads doesn't take a max cost per click on maximize clicks, conversions or conversion value again once the strategy changes, so a revert sets that strategy back without its max cost per click (spend stays within the daily budget and its guardrails). The preview of the change, and of the revert, says so. ## Amounts Bids use at most two decimals, or whole numbers in a currency without decimals, such as the yen. Roasby refuses a finer amount rather than rounding it, so the amount you confirm is the amount that is set. ## Ask your AI assistant Your assistant checks conversion tracking with `list_conversion_actions` before it suggests how a campaign should bid. - To change how a search campaign bids it uses `preview_update_bidding` (it reads the current bidding in `list_ad_entities`), then `update_bidding`. - To change the conversion goals it bids on, `preview_update_conversion_goals`, then `update_conversion_goals`. - For one bid, `preview_update_bid`, then `update_bid`. - For many bids, it uses `preview_update_bids` (an amount per item, or one rule: an amount, a change in percent or the first page bid up to a cap, optionally limited to the guardrails), then `update_bids`. Try: - *"Is conversion tracking set up right before I switch to maximize conversions?"* - *"Raise every keyword of the Primary FRCA ad group to its first page bid, at most 55 pounds, within my guardrails"* - *"Lower the bids of these ad groups by 15%"* ## Limitations - Conversion goals: - your assistant can change which goals a search campaign bids on, not on ChatGPT Ads, whose campaigns show no conversion goals; - Roasby never creates a custom goal; - conversion actions are read only, every few hours, and changed in the ad platform. - Bidding: - a campaign's own strategy only (not portfolio strategies), on Google Ads and Microsoft Ads search campaigns; - ad group target CPAs on Google Ads only, under a campaign that has a target CPA; - a target taken away and set again keeps the max bid change per step from the one before; - your assistant's reverts keep the guardrails; a revert you make on the **Change log** page restores the exact earlier target; - ChatGPT Ads bidding is changed in ChatGPT Ads Manager. - On Microsoft Ads, Roasby: - doesn't change target impression share yet; - never adds a target CPA or target ROAS to (or takes one from) a campaign that keeps its strategy; - doesn't move a campaign to or from the account's conversion goals: Microsoft offers no way to set those back; - uses enhanced cost per click for manual cost per click; - keeps a strategy's max cost per click while the strategy stays, but can't set it again after a switch: a revert then comes back without it. - Bulk bid changes: - they keep the max bid change per step: a larger rise takes several steps (a cut takes none) (Roasby limits each one for you if you ask, but never passes the guardrails); - first page bid estimates exist only for keywords, not under automated bidding, and on Microsoft Ads only for keywords with recent activity: keywords without one are left out when you raise keywords to their first page bid; - estimates are as of Roasby's last sync. - ChatGPT Ads: max bids on ad groups only. See every limit by platform on [Limitations](/docs/limitations). --- # Edit campaigns with your AI > Ask your AI assistant to edit search campaign settings, ad text and keywords, and to add keywords, ad groups, ads and negative keywords, all paused. Your AI assistant edits the search campaigns you already have: their settings, ad text and keywords, and it adds keywords, ad groups, ads and negative keywords to them. There is no web form for these; the [Campaigns](/docs/campaigns) page shows the result. Your assistant shows you a preview of every change and makes it only after you confirm. Everything it adds starts paused, nothing is removed, and every change is added to the [change log](/docs/change-log), where you can revert it (see the [safety model](/docs/safety-model)). ## Editing campaign settings through your AI assistant Your assistant can change the settings of a Google Ads or Microsoft Ads search campaign, one or more sections at once. It reads the current settings with `list_ad_entities`, checks the change with `preview_update_campaign_settings`, and makes it with `update_campaign_settings` once you confirm. Try *"Show the Brand campaign only on weekdays from 8 to 20, and bid 20% more on mobile"* or *"Add Germany and Austria to the Brand campaign and turn off search partners"*. ### Settings you can change - **Locations**: the countries it targets (such as US or DE) and who sees the ads there: **people in or interested in them**, or **only people in them**. The countries you name replace its country targets; places you excluded stay as they are. - **Networks**: **Search partners** on or off. On Microsoft Ads this is kept per ad group, so it is set on all of the campaign's ad groups. Roasby never turns the Google Display Network on or off. - **Tracking**: the final URL suffix and tracking template, or remove either one. - **Schedule**: the days and hours ads show, each time slot with an optional bid adjustment (-90% to +900%). - Times are in quarter hours, in the ad account's time zone (Google Ads) or the campaign's (Microsoft Ads). - With no time slots, ads show all day, every day. - Google Ads takes 6 time slots a day; Microsoft Ads 7 a day and 49 in all. - Slots of one day may not overlap. - **Devices**: the bid adjustment for mobile, tablet and desktop, in percent: 20 bids 20% more, -30 bids 30% less, and -100 shows no ads on that device. Google Ads takes -90% to +900% (or -100%), Microsoft Ads -100% to +900%. - **Rotation**: **Optimize** (the platform prefers the ads it expects to do best) or **Rotate evenly**. Both platforms keep it per ad group, so it is set on all of the campaign's ad groups. - **Languages** (Microsoft Ads only): the languages of the people the ads show to; none means every language. Google Ads search campaigns have no language targeting: Google matches each search's language itself. The preview shows each section before and after, what the guardrails limit or refuse, and anything only the ad platform can do. If the settings change before you confirm, your assistant previews the change again. All sections change together as one **Settings changed** entry in the [change log](/docs/change-log). Reverting it puts back every section it changed (refused if one of them changed again since). When new countries include EU countries on Google Ads and the campaign has not declared whether it contains EU political advertising, the preview asks you to declare it in Google Ads. ### Bid adjustments Bid adjustments count like bids, because they raise what you pay: - Devices and time slots multiply, so Roasby checks each device in each hour of the week that shows ads. The device adjustment times the hour's adjustment (as multipliers, +20% is 1.2) may rise at most your account's **max bid change** per step. At a 50% step, mobile +0% may go to +50%, or mobile +20% with Mondays at +25%, but not both to +50%. - A device with no ads (-100%), or hours the schedule left out, come back at 0% at most in one step; a rise past that is a later step. - No schedule means every hour at 0%, so taking a schedule away counts as a rise for hours that ran lower or ran no ads. - Lowering an adjustment and switching a device off are always allowed. A rise past that is refused, naming each device and time slot, unless you ask your assistant to limit the bid adjustments to the largest step the guardrails allow. Roasby then lowers each rise as far as needed and lists them (a schedule that would rise too far when taken away stays for now), so you can make the next step once the change is applied. See [Bid adjustments](/docs/safety-model#bid-adjustments) for the exact rule. ## Editing ad text through your AI assistant Your assistant can change the text of a responsive search ad on Google Ads or Microsoft Ads in place: the ad keeps its status, its history and its results. The ad platform reviews the new text again, so the ad may show as under review until it is approved. It reads the ads' text with `list_ad_entities`, checks the edit with `preview_update_ads`, and makes it with `update_ads` once you confirm. Try *"Rewrite the second headline of the Trail ad and pin it to position 1"* or *"Change 'Fast shipping' to 'Fast delivery' in every ad of the Running shoes campaign"*. You can change: - **Headlines** (3 to 15) and **descriptions** (2 to 4), each shown in any position or pinned to one (headlines 1 to 3, descriptions 1 to 2). - **Display path 1** and **Display path 2**, and the **final URL** the ad links to. A display path can also be removed. What you change follows the same rules as every new ad (see [Adding responsive search ads](#adding-responsive-search-ads-through-your-ai-assistant)), and none of it may be left empty; what you leave as it is is never checked again. Keyword insertion such as `{KeyWord:Trail shoes}` counts by its default text. ### Find and replace A find and replace changes the same text in many ads at once: in every responsive search ad of an ad group, a campaign or an ad account, or in the ads you name. - The text is found exactly as it is, spaces included (it is never a pattern). - The replacement can be empty to take the text away. - You can limit it to headlines and descriptions, display paths or the final URL, and choose whether letter case must match. - Ads without the text stay as they are. ### Preview and revert The preview shows each ad's text before and after. An ad whose new text breaks a rule (too long, two headlines the same, a headline left empty) is refused on its own with the reason; the others can still change. If an ad's text changes before you confirm, your assistant previews the edit again. The ads change together as one entry in the [change log](/docs/change-log) (**Ads edited**), which shows each part before and after (**Ad text changed**). Reverting it, or one ad of it, writes the old text back (refused if the ad's text changed again since). ## Editing keywords through your AI assistant Your assistant can change a keyword on Google Ads or Microsoft Ads: - its text; - its match type; - its own final URL (the page it links to instead of its ads' final URLs), or take that final URL away so the ads' final URLs are used again. It checks the change with `preview_update_keywords` and makes it with `update_keywords` once you confirm. Try *"Make every broad match keyword in the Trail ad group phrase match"* or *"Change the keyword 'cheap trail shoe' to 'affordable trail shoes' and send it to our sale page"*. How the change is made depends on the ad platform: - **A final URL** changes in place on both platforms: the keyword keeps its status, its history and its results. - **A match type** changes in place on Microsoft Ads. Google Ads can't change it, so Roasby replaces the keyword. - **A new text** replaces the keyword on both platforms. ### When a keyword is replaced A replace adds the new keyword to the same ad group, **paused**, with the old keyword's own bid and final URL (unless you change the final URL), and pauses the old one. Nothing is removed. - Until you enable the new keyword, the keyword shows no ads. - The new keyword starts without the old one's history (no Quality Score data yet). - Enable the new keyword on the [Campaigns](/docs/campaigns) page or through your assistant when you are ready: your assistant offers to. ### Preview, refusals and revert The preview shows each keyword before and after, which ones are replaced, and the ones refused with the reason. Letter case and spacing alone change nothing. A change is refused when: - the ad group already has a keyword with the new text and match type (enable that one instead: the preview names it); - a negative keyword of the ad group or campaign blocks the new text; - the new text breaks the platform's keyword rules; - or the copied bid is above your max bid. If a keyword changes before you confirm, your assistant previews the change again. The keywords change together as one entry in the [change log](/docs/change-log) (**Keywords changed**), which shows each keyword as **Keyword replaced** or **Keyword changed** with each part before and after. Reverting it, or one keyword of it, pauses the new keyword and gives the old one its status back, or sets a change in place back (refused if either keyword changed again since). ## Adding keywords through your AI assistant Your assistant can add many keywords to an ad group you already have, on Google Ads and Microsoft Ads search campaigns. Like creating campaigns, this is done only through your assistant. Each keyword has its text (in any language), a match type and, if you want, its own max bid and its own landing page; without them it uses the ad group's bid and the ad's landing page. - **Each keyword is checked on its own.** The preview lists the keywords that will be added and every refused one with the reason. Only the keywords that pass are added. A keyword is refused when it is: - longer than the ad platform takes (80 characters and 10 words on Google Ads, 100 characters on Microsoft Ads); - using a character Google Ads doesn't take in keywords (such as `!` or `?`), or written as `[exact]` or `"phrase"` (the match type goes in its own field); - the same keyword twice in the list; - a keyword the ad group already has with that match type (enabled or paused; a removed one can be added again); - blocked by a negative keyword on the ad group or its campaign, which would stop it from ever showing ads: a broad negative blocks keywords that have all its words, in any order; a phrase negative those that have its words in that order; an exact negative the same words; - a bid above the account's max bid, once one is set under **Guardrails**; - or a bid on a campaign with automated bidding. - **Every new keyword starts paused**, even in an ad group that is running, so nothing changes until you say so. Your assistant then offers to enable exactly those keywords, with one more preview and confirmation. - **One change.** The keywords are one batch: one entry in the change log (**Keywords added to** the ad group, with how many), which opens to each keyword and its result. **Revert batch** pauses the keywords it added; keywords are never removed. Keywords that are still paused have nothing to revert. - One add at a time runs per ad group: wait until it is applied before you add more there. To find keywords worth adding, ask your assistant for [keyword research](/docs/keyword-research). ## Adding ad groups through your AI assistant Your assistant can add ad groups to a search campaign you already have, on Google Ads and Microsoft Ads. Like creating campaigns, this is done only through your assistant. Each ad group has a name (in any language), a default max bid, and, if you want, its keywords (as when you add keywords), its negative keywords and up to 3 responsive search ads (with the same rules as every new ad, below). An ad group without an ad shows no ads. - **Each ad group is checked with everything in it.** The preview lists the ad groups that will be added and every refused one with the reason and the part that breaks the rule, for example the keyword that is too long. Only the ad groups that pass are added, each one whole. An ad group is refused when: - its name is too long (254 characters on Google Ads, 255 on Microsoft Ads); - the campaign already has an ad group with that name (enabled or paused; letter case and spacing don't count, and a removed ad group's name can be used again), or another ad group in the list has it; - the campaign would have more than 20,000 ad groups; - its bid breaks the rules below; - one of its keywords would be refused when you add keywords; - one of its keywords is blocked by one of its own negative keywords or a negative keyword of the campaign (by the negative's match type, as above); - one of its negative keywords breaks the keyword rules (such as a `%`), which would make the platform refuse the whole change; - or one of its negative keywords is broad match on Microsoft Ads. - **Bids.** On a campaign that uses the bids you set (manual cost per click, or enhanced cost per click on Microsoft Ads), every new ad group needs a default bid, within the account's max bid once one is set under **Guardrails**. On a campaign with automated bidding, the ad group and its keywords take no bids. - **Every new ad group starts paused**, even in a campaign that is running. - Its keywords and ad are created ready under it, so enabling the ad group alone starts it once its campaign runs. - Your assistant then offers to enable exactly those ad groups, with one more preview and confirmation. - Roasby doesn't enable any ad group (new or not) whose default bid, or the own bid of an enabled keyword in it, is above the account's max bid. - A new ad group in a campaign whose bidding Roasby hasn't synced yet is refused until the next sync. - **One change.** The ad groups are one batch: one entry in the change log (**Ad groups added to** the campaign, with how many), which opens to each ad group with its counts of keywords, negative keywords and ads, and its result. **Revert batch** pauses the ad groups it added; ad groups are never removed. Ad groups that are still paused have nothing to revert. - **Every part counts.** Each ad group, keyword, negative keyword and ad counts toward the number of items your workspace can change in one batch. - **On Microsoft Ads**, an ad group is created step by step. - If a later step fails (for example its ad), the change fails with the reason, and the ad group stays **paused** on the Campaigns page with what was made. - Finish it in Microsoft Ads (with its ad), and once Roasby's next sync shows its ad you or your assistant can enable it; or add it again under another name. - A new Microsoft Ads ad group shows on Microsoft's own search network only; turn on search partners for it in Microsoft Ads if you want them. - One add at a time runs per campaign: wait until it is applied before you add more there. ## Adding responsive search ads through your AI assistant Your assistant can add responsive search ads to ad groups you already have, in search campaigns on Google Ads and Microsoft Ads. Like creating campaigns, this is done only through your assistant. ### Rules for every new ad Every ad Roasby creates, in a new campaign, a new ad group or an ad group you have, follows the same rules: - **Headlines and descriptions.** 3 to 15 headlines of up to 30 characters and 2 to 4 descriptions of up to 90, in any language. Characters of Chinese, Japanese and Korean, full-width characters and emoji count as two, so a headline holds 15 of them. Headlines must differ from each other (letter case and spacing don't count), and so must descriptions. - **Pinning.** You can pin a headline to position 1, 2 or 3 and a description to position 1 or 2, so it always shows there. - Pinned headlines and descriptions show only in their position, so every other position needs one of its own: keep at least as many unpinned headlines as headline positions nothing is pinned to, and the same for descriptions. - Two headlines pinned to position 1 with one unpinned is refused, since positions 2 and 3 would share one headline. - Pinning is allowed but lowers the ad's strength, since the ad platform can test fewer combinations: pin only text that must show, and pin 2 or 3 headlines to a position rather than one. - **Display paths and tracking.** Two optional display paths of up to 15 characters each (no spaces or slashes; the second only with the first), the https page the ad links to, and optionally a final URL suffix with tracking parameters such as `utm_source=google`, without a leading `?`. ### How new ads are added - **Each ad is checked on its own.** The preview lists the ads that will be added and every refused one with the reason and the part that breaks the rule, for example the headline that is too long. Only the ads that pass are added. - **Every new ad starts paused**, even in an ad group that is running. Your assistant then offers to enable exactly those ads, with one more preview and confirmation. An ad group runs at most 3 enabled responsive search ads, so enabling a fourth is refused: pause one of the others first. - **Policy review.** The ad platform still reviews every new ad against its advertising policies. If it refuses an ad, the change log says why in plain words. Change the wording and add the ad again; Roasby never asks for a policy exception, which only the ad platform's own website can request. See [Policy review](/docs/campaigns#policy-review). - **One change.** The ads are one batch: one entry in the change log (**Ads added**, with how many), which opens to each ad by its first headline and its result. **Revert batch** pauses the ads it added; ads are never removed. Ads that are still paused have nothing to revert. - One add at a time runs per ad group: wait until it is applied before you add more there. ## Negative keywords A negative keyword on a campaign or an ad group stops its ads from showing for that search. Each has a match type: **exact** excludes only that search, **phrase** also searches that contain it, **broad** searches with all its words (Google Ads only: Microsoft Ads has exact and phrase negative keywords). - To exclude searches people already made, open the [Search terms](/docs/search-terms) page: it shows which searches are worth excluding, and **Exclude** adds one or several of them. - For any other negative keywords, ask your assistant. It checks them with `preview_add_negative_keywords` and adds them with `add_negative_keywords` once you confirm. Try *"Add 'jobs' and 'repair' as phrase match negative keywords to the Running shoes campaign"*. Negative keywords the campaign or ad group already has stay as they are. On Microsoft Ads, if some keywords are refused, the others are still added, and the change log names the refused ones and why. Reverting the change takes away exactly the negative keywords it added, never ones that were there before. App campaigns and their ad groups do not take negative keywords. ## Ask your AI assistant Every edit takes two steps: a preview tool shows the change and the guardrails, you confirm, then the write tool applies it. - **Settings:** `preview_update_campaign_settings` with only the sections to change (it reads the current ones in `list_ad_entities`), then `update_campaign_settings`. - **Ad text:** it reads the text in `list_ad_entities`, then uses `preview_update_ads` (the parts that change for each ad, or a find and replace across an ad account, campaign or ad group), then `update_ads`. - **Keywords:** to change keywords' text, match type or own final URL, `preview_update_keywords`, then `update_keywords`. A replaced keyword's new keyword starts paused, and it offers to enable it with `preview_enable_entities` once the change is applied. - **New keywords:** `preview_add_keywords`, then `add_keywords`. The keywords are added paused, and it can enable them with `preview_enable_entities`. - **New ad groups:** `preview_add_ad_groups`, then `add_ad_groups`. The ad groups are added paused with their keywords and ads, and it can enable them with `preview_enable_entities`. - **New ads:** `preview_add_responsive_search_ads`, then `add_responsive_search_ads`. The ads are added paused, and it can enable them with `preview_enable_entities`. - **Negative keywords:** `preview_add_negative_keywords`, then `add_negative_keywords`. Try: - *"Add three ad groups to the Running shoes campaign: trail, road and kids, each with its keywords and an ad"* - *"Add these 30 keywords as phrase match to the Running shoes ad group"* - *"Add a second ad to the Trail ad group, with our brand name pinned as the first headline"* - *"Change 'Free shipping' to 'Free delivery' in every ad of the Running shoes campaign"* ## Limitations - Roasby can't edit ad types other than responsive search ads. Do that in the ad platform itself. - Campaign settings: - search campaigns only, and only once Roasby has read them (after a sync); - countries only: a campaign that also targets regions, cities or a radius keeps its locations, which you change in the ad platform; - excluded places, location bid adjustments, the Google Display Network and Google's connected TV adjustment aren't edited; - Google Ads takes 6 schedule time slots a day, Microsoft Ads 7 a day and 49 in all; time slots run in quarter hours; - bid adjustments: -90% to +900% for a time slot, and for a device -100% (no ads) or -90% to +900% on Google Ads, -100% to +900% on Microsoft Ads; a rise is limited to your max bid change per step, for each device in each scheduled hour; - ad rotation (and on Microsoft Ads search partners) is set on every ad group the campaign has now, so it needs the campaign's ad groups synced; ad groups added later get the platform's default; - a section someone changed in the ad platform since Roasby last read it is not sent: Roasby reads the account again and the change log says which, so you can review it once more; - on Microsoft Ads the sections are sent one after another: new countries are added before the old ones are taken away, and if the platform refuses a new schedule, Roasby puts the old time slots back (and alerts its team if it cannot); - if the platform refuses a section, the ones before it stay applied, and the change log says which; - Google Ads search campaigns have no language targeting. - Ad text: - responsive search ads only, once Roasby has read their text (after a sync); - headlines, descriptions, their pins, display paths and the final URL; an ad's own final URL suffix and a second final URL are kept as they are; - one edit at a time runs per ad; - a find and replace looks at up to 10,000 ads; narrow it to a campaign, an ad group or some ads; - an ad someone changed in the ad platform since Roasby last read it is not changed: Roasby reads the account again, and you review the change once more; - the ad platform reviews the new text again; a policy review or exception is only in its own website. - Keywords: - only in search campaigns, once Roasby has read their own final URL (after a sync); - a new text, and a new match type on Google Ads, replace the keyword: the new one is added paused and starts without history, and the old one is paused, never removed; - one change at a time runs per keyword; - a keyword someone changed in the ad platform since Roasby last read it is not changed in place: Roasby reads the account again, and you review the change once more. - New keywords: - at most 80 characters and 10 words on Google Ads and 100 characters on Microsoft Ads, without the characters Google Ads refuses; - only on search campaigns; - at most 20,000 keywords and negative keywords in one ad group; - there is no web page for adding keywords: ask your assistant. - New ad groups: - only in search campaigns, with a name of up to 254 characters on Google Ads and 255 on Microsoft Ads; - at most 100 ad groups in one request, 1,000 keywords, 100 negative keywords and 3 responsive search ads each; - at most 20,000 ad groups in one campaign, and at most 10,000 items in one request; - ad groups have no start or end dates of their own on Google Ads (only campaigns do), so Roasby doesn't set them; - there is no web page for adding ad groups: ask your assistant. - New responsive search ads: - only in ad groups of search campaigns, at most 100 ads in one request, created paused; - at most 3 enabled ones per ad group, and at most 100 ads (enabled and paused) in one Microsoft Ads ad group; - characters of Chinese, Japanese and Korean and emoji count as two toward the character limits; - a policy review or exception for a refused ad is only in the ad platform's own website; - there is no web page for adding ads: ask your assistant. - Microsoft Ads: there are no broad match negative keywords. - ChatGPT Ads: no keywords or negative keywords (adding keywords is refused there), no new ad groups in an existing campaign, no responsive search ads (and no ad text edits). - A batch changes one ad account at a time, with only so many items in one batch; split larger ones. - Roasby never deletes anything: pause instead. See every limit by platform on [Limitations](/docs/limitations). --- # Create campaigns with your AI > Ask your AI assistant to build a whole Google Ads, Microsoft Ads or ChatGPT Ads campaign in one preview, created paused until you enable it. You create campaigns by asking your AI assistant (see [Connect your AI](/docs/connect-your-ai)). It is told to show you a preview of the whole campaign and create it only after you confirm. The new campaign then shows on the [Campaigns](/docs/campaigns) page, paused, until you enable it. ## Creating a search campaign Your assistant creates a complete Google Ads or Microsoft Ads search campaign in one step (`create_search_campaign`), with one preview and one confirmation. The campaign comes with: - its daily budget; - bidding: manual cost per click, maximize clicks or maximize conversions; - its targeting; - its own negative keywords; - and all of its ad groups. ### The whole campaign at once - **Ad groups:** as many as you need (up to 1,000), each with: - a name; - its keywords, each with its match type and, if you want, its own max bid and landing page; - its negative keywords; - up to 3 responsive search ads, with the [same rules as every new ad](/docs/editing-campaigns#adding-responsive-search-ads-through-your-ai-assistant). Each ad group is checked like one you [add to a campaign](/docs/editing-campaigns#adding-ad-groups-through-your-ai-assistant). - **Bids:** with manual cost per click, the campaign's max cost per click is the default bid of every ad group. It, an ad group's or a keyword's own bid, and a maximize clicks ceiling all stay within the account's max bid once one is set. With automated bidding, ad groups and keywords take no bids. - **Negative keywords** of the whole campaign (up to 10,000), besides those of each ad group. - **All or nothing.** If any part breaks a rule, nothing is created, and the preview names every part that does, such as *ad group "Trail" › keyword: shoes! (Exact match)*. Your assistant fixes them and shows you a new preview. - **One change.** The campaign is one entry in the [change log](/docs/change-log), with how many ad groups, keywords, negative keywords and ads it has. It counts as one change toward your workspace's limits, but every part (the campaign and each ad group, keyword, negative keyword and ad) counts toward the number of items your workspace can create in one change. - **Size:** one campaign holds at most 10,000 operations: the budget, the campaign, each country, ad group, keyword, negative keyword and ad count one each. Your assistant splits a larger campaign: it creates the campaign with part of its ad groups, then adds the rest [to the campaign](/docs/editing-campaigns#adding-ad-groups-through-your-ai-assistant). - **From a file:** there is nothing to upload. Give your assistant the file you have (a Google Ads Editor export, a spreadsheet, a list of keywords) and it fills the campaign from it, asks you for what the file doesn't say (the daily budget, the countries, the EU political ads question), then shows you the preview. ### Targeting and tracking - **Countries:** any number of countries, each once, as two-letter codes (US, DE...). Roasby doesn't judge which countries a platform targets: the ad platform answers when the campaign is created, and a country it refuses fails the create with its reason. - **Who sees the ads there:** people in the countries or searching for or interested in them (the default, as in the ad platforms), or **only people in the countries** (or regularly there). - **Search partners:** on or off (off by default). On also shows the ads on the ad platform's search partner sites. - **Languages:** - On Microsoft Ads, the languages of the people your ads are for, from Microsoft's list of ad languages (default: all languages). Microsoft Advertising may not offer every language in every account yet, and refuses the campaign if one isn't available. - On Google Ads, search campaigns have no language targeting: Google matches the language of each search automatically, from the search and the ad text, so write your ads in the languages you want to reach. The preview and the result say so when you ask for languages. - **Final URL suffix:** parameters added to the end of every landing page address, such as `utm_source=google&utm_medium=cpc` (without a leading `?`). - **Tracking template:** a campaign tracking template that starts with `https://`, `http://` or a landing page tag, and contains a landing page tag: `{lpurl}`, `{lpurl+2}`, `{lpurl+3}`, `{unescapedlpurl}` or `{escapedlpurl}`. The preview lists every one of these choices before you confirm, and the change log keeps them. ### Paused, within your guardrails - **Always paused.** The campaign is always created **paused**. Its ad groups, keywords and ads are enabled under it, so nothing runs until you **Enable** the campaign itself. - **When Enable is refused.** Roasby refuses to enable it: - if the budget is above the max daily budget of the ad account; - while the campaign is still being created; - or if it was only partly created and its next sync doesn't show every part yet: its negative keywords, and each ad group with all its keywords, negative keywords and ads. Roasby can't see a campaign's targeting, so if the ad platform stopped before the countries were set, finish the campaign in the ad platform and enable it there, or pause it and create it again under another name. - **Max daily budget.** The ad account needs a **max daily budget**, and the new budget must stay within it. Only people set it: open [Ad accounts](/docs/ad-accounts), choose **Guardrails** on the account, set the amount and save. If it is missing, your assistant gives you a link to that form. - **Revert.** Reverting the change in the change log pauses the campaign again. Nothing is ever deleted. ### EU political advertising - Your assistant asks you whether the campaign contains **EU political advertising**. This is your own declaration to Google; Roasby never answers it for you. Microsoft Ads accepts no political ads, so there the answer must be no. - Since April 2026, Google Ads refuses every campaign change in an account while one of its campaigns hasn't declared whether it contains EU political advertising. Roasby reads this when it syncs, and the preview of any change in that account names the campaigns to declare. - Roasby still sends the change (its copy may be older than your declaration, and pausing must always be possible); if Google refuses it, the change log says why. Declare them (or the whole account) in the Google Ads web interface. ### On Microsoft Ads - **Manual cost per click** becomes **enhanced cost per click**: Microsoft no longer bids manually on search campaigns, so it raises or lowers your max cost per click to win conversions. The preview says so before you confirm. - **Search partners** are Microsoft's syndicated search partners (set on the ad group). - **Only people in the countries** is Microsoft's *People in your targeted locations* option. - Microsoft Ads makes a campaign piece by piece: the campaign, its targeting and negative keywords, then each ad group with its keywords, negative keywords and ads. A large campaign takes a few minutes; it stays pending in the change log, paused on the Campaigns page, until all of it is made (at most a day). - If Microsoft accepts the campaign but refuses one of its parts, or stops answering, the change fails with the reason and says how many ad groups were made. Roasby never sends a part twice. The campaign stays **paused**, and Roasby usually syncs the account within a few minutes, so the parts Microsoft did make show on the Campaigns page: finish it in Microsoft Ads, or create the campaign again under another name. ## Creating a ChatGPT Ads campaign On a ChatGPT Ads account, your assistant creates a complete ChatGPT Ads campaign in one step (`create_chat_campaign`): - a **daily budget**, and the campaign pays **per click**: either a **max cost per click** you set, or **maximize clicks**, where ChatGPT Ads sets the bids; - the **countries** it shows in (leave them empty for every country ChatGPT Ads serves) and optional start and end dates; - one ad group with **context hints**: the topics and situations of the conversations your ads fit, such as *planning a trip to Japan*. They guide where ads show; they are not keywords; - one **chat card ad**: a title (3 to 50 characters), a short text (up to 100), the page it links to, and an **image link**: an https link to a JPEG, PNG or WebP image of at least 640 × 640 pixels. Roasby doesn't open the image itself: ChatGPT Ads downloads it after you confirm, so check that the link opens the image (a broken link stops the campaign from being created). As with search campaigns: - the campaign is always created **paused** with its ad group and ad enabled under it; - the ad account needs a **max daily budget** and the new budget must stay within it; - reverting the change pauses the campaign. ChatGPT Ads needs at least $25 a day in USD accounts. ChatGPT Ads reviews the ad and its image once it is created; a rejected ad shows in [alerts](/docs/alerts). If ChatGPT Ads can't use the image, nothing is created. If it accepts the campaign but refuses the ad group or the ad, the change fails with the reason and the campaign stays **paused** on the Campaigns page: finish it in ChatGPT Ads Manager, or create the campaign again under another name. ## Ask your AI assistant Your assistant shows the whole campaign with `preview_create_search_campaign` or `preview_create_chat_campaign`, you confirm, then `create_search_campaign` or `create_chat_campaign` creates it, paused. Once it is created, enable it on the [Campaigns](/docs/campaigns) page or ask your assistant to. To add more to it later, see [Edit campaigns with your AI](/docs/editing-campaigns). Try: - *"Create a paused search campaign for our running shoes in the US and Canada, 50 dollars a day"* - *"Build a paused campaign from this Google Ads Editor export, with every ad group, keyword and ad in it"* - *"Create a paused ChatGPT Ads campaign for our Japan trips, 30 dollars a day"* ## Limitations - A new search campaign holds at most: - 1,000 ad groups, each with up to 1,000 keywords, 100 negative keywords and 3 responsive search ads; - 10,000 negative keywords of its own; - 10,000 operations in all; a larger one is created in parts. - It targets whole countries (no regions, cities or radius). - There is no file import: your assistant reads your file and fills the campaign itself. - Microsoft Ads: - manual cost per click becomes enhanced cost per click; - political ads are not accepted; - the languages come from Microsoft's list of ad languages, and some are not yet available in every account. - Google Ads: - language targeting no longer exists on Search campaigns (Google matches languages itself, so the languages you ask for are only noted); - the EU political ads declaration (for a campaign Roasby didn't create, or the whole account) and turning off automatically created assets are only in the Google Ads web interface. Your assistant lists those steps when it creates a Google Ads campaign, or when a missing declaration blocks a change. - ChatGPT Ads: at least $25 a day in USD accounts. - Roasby never deletes anything: pause instead. See every limit by platform on [Limitations](/docs/limitations). --- # Sitelinks, callouts and other assets > See the sitelinks, callouts, structured snippets, prices and promotions on your campaigns, and ask your AI assistant to add, pause or enable them. Sitelinks, callouts, structured snippets, prices and promotions add extra lines and links to your search ads. You see them on the [Campaigns](/docs/campaigns) page, and your AI assistant adds, pauses and enables them. ## Sitelinks, callouts and other assets When you open one ad account, campaign or ad group, an **Assets** list under its table shows the sitelinks, callouts, structured snippets, prices and promotions linked to it, with their status. The list is read only: your AI assistant adds, pauses and enables them. ChatGPT Ads has no such assets. ## Adding assets through your AI assistant Your assistant can add sitelinks, callouts, structured snippets, prices and promotions to a whole Google Ads account, to a Google Ads or Microsoft Ads search campaign, or to one of its ad groups. It reads what is linked with `list_assets`, checks the new assets with `preview_add_assets`, and adds them with `add_assets` once you confirm. Try *"Add sitelinks for Contact, Pricing and Book a call to the Brand campaign"* or *"Add a 20% off Black Friday promotion to the Shoes ad group"*. ### What each asset takes Each asset is checked on its own: - **Sitelinks:** text of up to 25 characters, and descriptions of up to 35 (both or neither). - **Callouts:** up to 25 characters. - **Structured snippets:** one of the fixed headers and 3 to 10 different values of up to 25 characters. - **Prices:** 3 to 8 rows, each with its own header, a description, a price and a landing page. - **Promotions:** its item (up to 20 characters), a percent or an amount off, at most one of a promotion code and a minimum order, and dates that have not passed. Characters of Chinese, Japanese and Korean and emoji count as two. Every landing page is a full https address. The preview names the part that breaks a rule, and only the assets that pass are added. ### How new assets are added - **Prices in their own currency.** Each price row has its own currency, which may differ from the ad account's. Microsoft Ads takes only some currencies, and promotions only in some languages; the preview says so. - **Never twice.** An asset with the same text that is already linked to the same place, enabled or paused, is refused: your assistant offers to enable the paused one instead. - **On Google Ads every new asset is linked paused**, even in a running campaign, so nothing shows until you enable it. Your assistant then offers to enable exactly those links, with one more preview and confirmation. - **On Microsoft Ads, which can't pause an asset link**, Roasby links new assets only to a paused campaign or ad group, never to a whole account, so they show once you enable it. - It checks with Microsoft Ads again just before it adds them, and a campaign Microsoft Ads suspended counts as running, since it can serve again without you. - Microsoft Ads shows callouts only when a campaign or ad group has 2 to 20 of them, and each place takes at most 20 assets of a type. - **One change.** The assets are one batch: one entry in the [change log](/docs/change-log), which opens to each asset and its result. **Revert batch** pauses the links it added (on Microsoft Ads takes them away); assets are never removed. Links that are still paused have nothing to revert. - One add at a time runs per place. - **Several places at once.** Your assistant can add the same assets to up to 20 campaigns or ad groups of one ad account in one preview and one confirmation; every asset goes to each of them. - **Sitelinks to another site.** When a sitelink goes to another website than the ads where it is linked, the preview warns you, so a typo or a wrong site is caught before the platform's review. - **On Microsoft Ads, a busy moment never makes a copy.** When Microsoft Ads has added an asset but was too busy to link it, Roasby links that same asset when it tries again, instead of adding it a second time. ## Pausing and enabling Your assistant pauses or enables an asset link like any other item (see the [safety model](/docs/safety-model)). On Microsoft Ads pausing takes the link away and enabling links it again; the asset itself stays in the ad account. ## Ask your AI assistant - `list_assets` lists the linked assets, each with the Roasby ID of its link, where it is linked (the whole ad account, a campaign or an ad group), its status and its content, and whether a pause or enable of it is still being applied. It can narrow the list with `ad_account_id`, `campaign_id`, `ad_group_id`, `type` or `status`; removed links are left out unless `include_removed` is true. - `preview_add_assets` shows the assets that may be added and the refused ones with why, and returns one `confirmation_token` for all of them, valid for 10 minutes, once. `add_assets` then adds them. They take one place (`ad_account_id`, `campaign_id` or `ad_group_id`) or several (`campaign_ids` or `ad_group_ids`, up to 20 of one ad account). - To pause or enable a link, it uses `preview_pause_entity` or `preview_enable_entity` with the link's ID, then `pause_entity` or `enable_entity` once you confirm. Try: - *"Which sitelinks and callouts does the Brand campaign have?"* - *"Add sitelinks for Contact, Pricing and Book a call to the Brand campaign"* - *"Add a 20% off Black Friday promotion to the Shoes ad group"* ## Limitations - Roasby adds sitelinks, callouts, structured snippets, prices and promotions and pauses or enables them, but it can't change an asset's text, or add images, logos or business names. Do that in the ad platform itself. - On Microsoft Ads, which can't pause an asset link, new assets are linked only to a paused campaign or ad group, never to a whole account. - Google Ads: turning off automatically created assets is only in the Google Ads web interface. - Sitelinks, callouts and other assets have no policy findings in Roasby. - ChatGPT Ads has no such assets. - Roasby never deletes anything: pause instead. See every limit by platform on [Limitations](/docs/limitations). --- # Search terms and wasted spend > See what people searched before your ads showed, find the searches and keywords that cost money without conversions, and exclude them as negative keywords. Open **Search terms** in the sidebar of your workspace. It shows what people typed before one of your Google Ads or Microsoft Ads ads showed (ChatGPT Ads has no search terms or keywords), per ad group, over the last 7, 30 or 90 complete days, with what each search cost and brought in. The data is as fresh as the account's last sync (**Sync now** on the [Ad accounts](/docs/ad-accounts) page updates it). ## Finding searches - Pick the **period** with the switch, and an **ad account** and a **campaign** from their menus (the campaign menu lists the current campaigns of the chosen account). You can also open **Search terms** from the [Campaigns](/docs/campaigns) page to start on that account or campaign. - **Search** narrows the list to searches containing your text. - Searches are sorted by spend, largest first. An **Excluded** badge means you already excluded this exact search through Roasby. - Searches that cost money without a conversion can carry an AI label: **Irrelevant** (red), **Competitor** (amber), **Brand** (blue) or **Relevant** (green). Confidently irrelevant ones show up on the [Recommendations](/docs/recommendations) page. ## Wasted spend The **Wasted spend** tab shows the money spent without any conversion in the period: - the total spent on searches without conversions, one card per currency (amounts are never converted between currencies); - the costliest **searches** without conversions that are not excluded yet; - the costliest **keywords** without conversions, which you can pause on the Campaigns page. A search you excluded directly in Google Ads or Microsoft Ads can still show here until it stops costing money. Excluding it again in Roasby is harmless: existing negative keywords are left as they are. ## Excluding a search **Exclude** on a search adds it as a negative keyword: choose **From the campaign** or **From the ad group**. To exclude several searches at once, tick them (all from one campaign) and choose **Exclude selected**; **From the ad group** shows when they are all in one ad group. You can edit the list and choose the match type before you confirm. Like every change, it goes through the [safety model](/docs/safety-model) and the [change log](/docs/change-log), where reverting it takes away exactly the negative keywords it added. ## Ask your AI assistant **Ask your AI** at the top of the page gives you a ready prompt: find the wasted search terms in your workspace and suggest negative keywords. **Copy prompt** copies it; **Ask Claude** and **Ask ChatGPT** open a new chat with the prompt typed in. The prompt names only your workspace: your assistant reads the searches through Roasby and shows you any change before it makes it. Your assistant reads the same data with `get_search_terms` and `find_wasted_spend`, then suggests negative keywords and is told to add them only after you confirm (`preview_add_negative_keywords`, then `add_negative_keywords`). Try *"Find the search terms that wasted money last month and suggest negative keywords"*. `list_recommendations` returns the exclusions Roasby already suggests. Roasby also copies the negative keywords set directly on campaigns and ad groups in Google Ads and Microsoft Ads when it syncs them, at most about twice a day (once a day in workspaces that sync less often), and leaves those searches out of Wasted spend and recommendations. Shared negative keyword lists are not read. ## Limitations - ChatGPT Ads has no search terms or keywords, so it doesn't appear here. - Ad platforms leave out searches too rare to report. Your assistant gets that spend as **other search terms** (the search campaigns' spend no listed search shows), so wasted spend may be larger than the listed searches. - The data is as fresh as the account's last sync. - Shared negative keyword lists are not read, so searches they exclude can still show here. - Up to 100 negative keywords in one change. Broad match negative keywords are Google Ads only. - Search terms show what people searched for your ads; for keywords you don't advertise on yet, ask your assistant for [keyword research](/docs/keyword-research). See every limit by platform on [Limitations](/docs/limitations). --- # Recommendations > Changes Roasby suggests from your recent results: search terms to exclude, keywords to pause and budgets to raise, ready to approve with one click. Open **Recommendations** in the sidebar of your workspace. Roasby looks at the last 30 complete days of each ad account and suggests changes that cut wasted spend or win back searches you miss, and updates the list with every sync. Nothing changes in your ad accounts until someone approves a recommendation. ## What Roasby suggests - **Exclude search term.** A search cost money without a conversion anywhere in the ad account, and Roasby's AI judged it unrelated to what you offer (for example someone looking for jobs, repairs or free downloads). Approving it adds the search as an **exact** negative keyword to its campaign. - **Pause keyword.** An enabled keyword got many clicks in the last 30 days without a single conversion. Approving it pauses the keyword. - **Raise budget.** An enabled search campaign lost a good share of its search impressions to its budget in the last 14 days (its daily budget ran out, see [impression share](/docs/campaigns#impression-share)), while it converted at least as cheaply as its ad account. Roasby needs an impression share on most of those days (at least 80%), all at today's budget. Approving it raises the daily budget to the amount shown. Each recommendation shows what it cost, its clicks and a short explanation. For the costliest ones the explanation is written by AI (marked with a sparkle). Roasby is careful on purpose: - Nothing is suggested for an ad account that had no conversion at all in the period, because missing conversion tracking would make everything look wasted. - Searches that name your ad account (usually your brand) are never suggested for exclusion. - Searches the AI labels **brand** or **competitor** are only labelled, never suggested: bidding on them can be deliberate. - A search that already converted, even in another campaign, is not treated as waste. ## Budget raises stay within your guardrails The budget a **Raise budget** recommendation suggests is the one that could win back the lost searches, kept within the ad account's [guardrails](/docs/safety-model): at most one **max budget change** step above today's budget and at most the **max daily budget**. Roasby works it out again whenever you open the list, so a guardrail you change counts at once. When the guardrails leave no room (the budget is already at the max daily budget, or the max change allows no raise), the recommendation says which guardrail is in the way and can't be approved. Owners and admins get a link to change the guardrails; you can also dismiss it. Roasby only suggests a raise for a campaign with a daily budget of its own (not a shared or lifetime budget) on Google Ads and Microsoft Ads. When the budget changes, in Roasby or in the ad platform, Roasby starts measuring again at the new budget and suggests more only once 14 days have run at it, so raises never pile up on old numbers. Meanwhile the recommendation says it is waiting and can't be approved. When the ad platform reports a share only as a bound (such as "below 10%" or "above 90%"), Roasby keeps it as that bound, shows it as **<10%**, **>90%**, **≤45%** or **≥45%**, and works out the raise from the bound: the suggestion is then on the low side, never higher than the numbers support. **Approve** raises the budget to exactly the amount on the page. If the suggestion changed since you opened it (a guardrail or the budget changed), nothing is changed and Roasby asks you to review it again. ## AI labels on search terms On the [Search terms](/docs/search-terms) page, searches that cost money without a conversion can carry an AI label: **Relevant**, **Irrelevant**, **Brand** or **Competitor**. Only a confident **Irrelevant** label becomes a recommendation, so a search without a label is never suggested for exclusion. ## Approve or dismiss - **Approve** makes the change through the [safety model](/docs/safety-model), exactly as if you had made it by hand: guardrails and limits apply, it is added to the [change log](/docs/change-log) and you can revert it there. - **Dismiss** changes nothing in the ad account; Roasby never suggests the same search or keyword again. Owners and admins can approve and dismiss, and members too when the workspace allows them to change ads. Everyone in the workspace can see the list. A recommendation closes by itself when it no longer applies: the search was excluded (also by your AI assistant), the keyword was paused, a conversion came in, or the campaign no longer loses impressions to its budget. The **Closed** tab shows approved, dismissed and resolved recommendations. ## Ask your AI assistant Each open recommendation has an **Ask your AI about this** menu. **Copy prompt** copies a prompt that asks your assistant to explain the recommendation and whether to approve it; **Ask Claude** and **Ask ChatGPT** open a new chat with it typed in. The prompt carries only the recommendation's ID and your workspace's name: your assistant reads the details through Roasby and shows you any change before it makes it. Your assistant sees the same list with `list_recommendations`: - **To approve**, each open recommendation names the preview tool and the exact arguments that approve it (`preview_add_negative_keywords`, `preview_pause_entity` or `preview_update_campaign_budget` with a budget within the guardrails). The assistant shows you the change, and it is told to make it only after you confirm. - **To dismiss** one, it uses `preview_archive_recommendation` and then `archive_recommendation`. - **When the guardrails block a budget raise**, the assistant gets no arguments, only which guardrail is in the way and the step for a person: only people change guardrails. Try *"What does Roasby recommend for my ad accounts? Walk me through the costliest ones."* or *"Which campaigns are limited by budget, and what would you raise?"* ## Limitations - Roasby suggests three kinds of change: excluding a search, pausing a keyword and raising a search campaign's daily budget. They need keywords or search impression share, so ChatGPT Ads accounts get none. - An ad account with no conversion in the period gets no recommendations. - Recommendations never run by themselves: someone approves each one, and there are no automatic rules. See every limit by platform on [Limitations](/docs/limitations). --- # Keyword research > Ask your AI assistant for keywords people search for, with monthly searches, trend, competition and bid estimates from your Google Ads or Microsoft Ads planner. You research keywords by asking your AI assistant (see [Connect your AI](/docs/connect-your-ai)). Roasby asks the keyword planner of one of your ad accounts (Google Ads Keyword Planner or Microsoft Ads Keyword Planner) for keywords and their estimates, so you can pick keywords people actually search before you build a campaign or add keywords. Research never changes anything in your ad accounts. There is no web page for keyword research: you ask your assistant. The old **Keyword research** address in Roasby now opens the [dashboard](/docs/dashboard), whose **Keyword ideas** prompt starts a search in one click. ## What you can ask for - **New keyword ideas** from up to 20 seed keywords (words or phrases that describe what you sell), a web page, or both. - **Volumes of your keywords** for up to 1,000 keywords you already have or are thinking of. Each search runs in one ad account: its platform does the research, and bid estimates come in its currency. Name up to 10 countries and the language people search in. Your assistant asks you for what you don't say. ## What you get back Keywords come with the most searched first: - **Average monthly searches**: the average of the last 12 months. When the platform gives no number, your assistant says so instead of guessing. - **Trend**: the searches of each of the last 12 months. - **Competition**: low, medium or high, from how many advertisers bid on the keyword. Google Ads adds a number from 0 to 100. - **Bid estimate**: on Google Ads, the low and high top-of-page bid (what advertisers paid at the 20th and 80th percentile); on Microsoft Ads, the bid it suggests. For your own keywords, Google Ads combines close variants (like *car* and *cars*) into one result, and your assistant tells you which keywords came back without a result. A new search usually takes a few seconds. The same search again within a day gives the same results at once. ## Ask your AI assistant Your assistant runs the research with `get_keyword_ideas` (from seed keywords or a web page) and `get_keyword_volumes` (for keywords you give it), and is told to use them before it builds a campaign or adds keywords. When a new search is still running, it asks again a few seconds later. Try: - *"Find keyword ideas for waterproof hiking boots in the US and Canada, then suggest ad groups for a new search campaign"* - *"How many people search for these 50 keywords in Germany each month, and what would they cost?"* - *"Find keyword ideas from our landing page that the Trail ad group doesn't have yet"* To add the keywords you pick, ask your assistant to add them to an ad group: see [Adding keywords](/docs/editing-campaigns#adding-keywords-through-your-ai-assistant). ## Limitations - The numbers are estimates. Google Ads rounds search volumes, and accounts with little or no ad spend may see broader rounded numbers. - ChatGPT Ads has no keyword research. Microsoft Ads researches keywords in English, French and German only; Google Ads in every language Roasby offers except Albanian, Bosnian, Macedonian and Maltese. - Countries only, no regions or cities. A disconnected ad account can't research keywords. - Each new search asks the ad platform, so a workspace can run only so many new searches an hour; searches you already ran don't count. Google Ads keyword research can pause for a while when Roasby's shared Google Ads capacity is busy. - The same search gives the same results for a day; after that, it asks the ad platform again. When the ad platform refuses a search, your assistant tells you why. See every limit by platform on [Limitations](/docs/limitations). --- # Anomaly alerts > Roasby watches every ad account for spend spikes, cost per conversion jumps and disapproved ads, and emails the workspace owner and admins. Open **Alerts** in the sidebar of your workspace. Roasby compares each ad account with its own recent history every time it syncs and flags what looks wrong. The workspace owner and admins get an email, and everyone in the workspace can see the list. To stop the emails, set **Alert emails** to **Off** in your [account settings](/docs/account-settings); alerts stay on the Alerts page and your AI assistant still sees them. ## What Roasby looks for - **Spend spike.** Yesterday a campaign spent at least twice its usual daily amount (its average over the 14 days before), far beyond its normal ups and downs. Very small campaigns, under a tenth of the account's usual daily spend, are left out. - **Cost per conversion jump.** A campaign's cost per conversion over 7 recent days is at least 1.5 times what it was over the 28 days before. The last 3 days are left out, because conversions keep coming in for a few days after a click. Both periods need enough conversions to compare (10 before, 5 recently). A campaign that **keeps spending without any conversion** for 7 days, at least three times its usual cost per conversion, is flagged too: that often means broken conversion tracking or a broken landing page. - **Ad disapproved.** The ad platform disapproved an enabled ad in an enabled ad group and campaign, so it stopped showing. The alert says why (for example **Why: Trademarks, Landing page not working**), and **Details** opens each finding: the headline or description it is about, what the platform flagged, the countries, and what you can change. A resolved alert keeps saying why the ad was disapproved. See [Policy review](/docs/campaigns#policy-review). An alert that gets worse while it is open (for example a spike that keeps growing) is emailed again. A newly connected ad account is checked once it has enough history. ## Severity Each alert has a severity from 1 (negligible) to 5 (critical). Roasby may skip the email for an alert that is not worth your attention; it still shows on the page, marked as not worth an email. ## When an alert closes You never need to dismiss an alert. It moves to the **Resolved** tab on its own once the problem is gone: the spend went back to normal, the cost per conversion recovered, or the ad was fixed, paused or removed. If the same problem comes back later, the alert opens again, and you get a new email unless the last one went out less than 7 days ago. If your workspace doesn't include anomaly alerts, the Alerts page says so. ## Ask your AI assistant Each open alert has an **Ask your AI about this** menu. **Copy prompt** copies a prompt that asks your assistant to explain the alert and suggest what to do; **Ask Claude** and **Ask ChatGPT** open a new chat with it typed in. The prompt carries only the alert's ID and your workspace's name: your assistant reads the details through Roasby and shows you any change before it makes it. Your assistant sees the same list with `list_alerts`, most severe first, with the numbers behind each alert and, for a disapproved ad, its policy findings. Try *"Are there any anomaly alerts in my ad accounts? Explain the worst one and what I could do about it."* or *"Why was my ad disapproved?"* Any change it suggests goes through the usual [preview and confirmation](/docs/safety-model#your-assistant-previews-every-change). ## Limitations - Roasby looks for three things: spend spikes, cost per conversion jumps and disapproved ads. - Alerts are checked when an account syncs, so they are as fresh as its last sync, and a new account is checked once it has enough history. - Alerts never change anything by themselves: you, or your assistant after you confirm, decide what to do. - Roasby never asks the ad platform to review a disapproved ad again or appeals for you: do that in the platform's own website. See every limit by platform on [Limitations](/docs/limitations). --- # Weekly report > Every Monday Roasby emails each workspace member a report of the last week across all ad platforms, with a short summary. Every Monday Roasby sums up the last week of each workspace and emails it to its members. Open **Reports** in the sidebar of your workspace to see every report sent so far. ## What the report covers The week is the last 7 complete days: it ends yesterday in your ad accounts' own time zones, the same days the dashboard shows for *Last 7 days*. Each report includes: - **A short AI-written summary** of 3 to 5 sentences at the top (some reports don't have one). - **Spend, conversions and conversion value** per currency, compared with the week before. Amounts in different currencies are never added together. Ad accounts that don't report conversion value show n/a, and their spend is left out of ROAS. Reports already sent keep their numbers. - **The split by ad platform** (Google Ads, Microsoft Ads, ChatGPT Ads). - **Rising and falling campaigns**: the campaigns whose conversions went up or down the most against the week before (up to 3 each). - **Missed impressions**: search campaigns that lost a good share of their search impressions to their budget or to ad rank that week, with their impression share (up to 5). - **What needs a look**: the number of open [alerts](/docs/alerts) and [recommendations](/docs/recommendations), and ad accounts that need to be reconnected. A report keeps the numbers it was sent with, even if an ad platform later corrects its figures. When a workspace has no history for the week before yet, the report says so instead of comparing. A workspace gets no report for a week in which none of its ad accounts ran (no impressions and no spend), or when it has no connected ad account. ## Download a report Open a report and use **Export** at the top right: - **Download PDF** opens your browser's print window with a clean, light layout (no sidebar). Choose *Save as PDF* as the destination. - **Download CSV** gives a spreadsheet file: the week's totals next to the week before, each ad platform, and the campaigns that rose or fell, one row each, with amounts in the currency's units. ## Stop the emails Every report email has an **Unsubscribe** link at the bottom, and most mail apps show an unsubscribe button too. It turns weekly report emails off for every workspace you are in. You can turn them on or off again under **Account settings → Weekly report emails**. The reports stay on each workspace's Reports page either way. ## Ask your AI assistant Your assistant reads the same report with `get_weekly_report` (the latest one, or one by its ID). For numbers that are up to date right now, it uses `get_performance_summary`. Try: - *"Get my weekly report and tell me which campaign I should look at first."* - *"Compare this week's report with last week's: what changed most?"* - *"Which campaigns in my weekly report missed impressions, and why?"* ## Limitations - A report keeps the numbers it was sent with, even if a platform corrects them later. - Weeks in which no ad account ran get no report. - Downloading a report as a PDF or CSV is done on the web; your assistant reads the same report instead. See every limit by platform on [Limitations](/docs/limitations). --- # Conversions > Ask your AI assistant how each Google Ads and Microsoft Ads account tracks conversions before you trust its numbers or change how a campaign bids. Your AI assistant tells you how each ad account tracks conversions, so you can check it before you trust conversion numbers or change how a campaign bids. Roasby has no web page for it: ask your assistant (see [Ask your AI assistant](#ask-your-ai-assistant)). ## What your assistant sees - **Bidding aims for**: on Google Ads, the account's goals that bidding uses, such as *Purchases (Website)*; on Microsoft Ads, its enabled conversion goals that count toward bidding. - **Problems Roasby found**, in plain words: - no enabled primary conversion action in the goals bidding uses; - a primary action that has not recorded a conversion since a date (on Microsoft Ads, a tag that is not verified or inactive). - **Every conversion action** (Google Ads) or **conversion goal** (Microsoft Ads), with: - where its conversions come from (**Website tag**, **Google Analytics 4 import**, **App**, **Phone calls**, **Uploaded or imported**, **Store visits and sales**); - what it counts and its goal; - whether it is **Primary** (bidding counts it and it is in the Conversions column) or **Secondary** (only observed); - its status, and whether it is recording, with its last conversion on Google Ads; - its conversions over the last 30 days, as the ad platform counts them (all conversions, including actions bidding doesn't use). - **Managed outside this account** marks one set up in a Google Ads manager account or shared by your Microsoft Ads customer. - Actions removed in the ad platform, when you ask for them. - Whether Roasby read the account recently: if it couldn't for a while, the answer may be out of date. ## Campaigns with their own goals On the [Campaigns](/docs/campaigns#conversion-goals) page, each campaign shows whether it uses the account's goals or its own. A campaign the ad platform reports no goals of its own for (as Google Ads does for campaigns made through its API, including the ones your assistant creates) uses the account's goals, the platform's default. Your assistant also lists the campaigns with their own goals and what each one bids on, including the conversion actions inside a Google Ads custom goal. ## How Roasby reads conversion tracking Roasby reads conversion tracking every few hours, after a sync, and also with **Sync now** and shortly after it creates a search campaign. - Create, edit or remove conversion actions in the ad platform. - Your AI assistant can change which goals a search campaign bids on (`preview_update_conversion_goals`), after you confirm. See [Bidding and goals](/docs/bidding-and-goals). - Google Analytics 4 key events are set up in Google Analytics and imported in Google Ads; until you import one, Roasby doesn't list it. - ChatGPT Ads conversion tracking isn't shown. ## Ask your AI assistant Your assistant reads the same data with `list_conversion_actions`: every conversion action or goal, what bidding aims for and the problems found. `primary_only` narrows it to the ones bidding counts, and `include_removed` adds the removed ones. It is told to check conversion tracking before it suggests a bidding strategy or a budget change. Try *"Is conversion tracking working in my Google Ads account?"*, *"Which conversion actions count toward bidding?"* or *"Has any primary conversion action stopped recording?"* ## Limitations - Conversion tracking is read only, every few hours: Roasby never creates or changes conversion actions, goals or Google Analytics 4 key events. It only changes which goals a campaign bids on, after you confirm. - Google Ads gives no tag status, so Roasby judges recording by the last conversion (when Google Ads received it, or for Google Analytics 4 imports its day; none in 7 days is **No recent conversions**). - ChatGPT Ads conversion tracking isn't read. See every limit by platform on [Limitations](/docs/limitations). --- # Change log > Every change made to your ads through Roasby, with who made it, the values before and after, its status, and how to revert it. Open **Change log** in the sidebar of your workspace. It lists every change made to your ads through Roasby, newest first: by you, a teammate, an AI assistant, or Roasby itself. Pick one account with the **Ad account** menu, or keep **All accounts**. **Change log** on an ad account in [Ad accounts](/docs/ad-accounts) opens it for that account. The short version is in the safety model: [A change log you can revert](/docs/safety-model#a-change-log-you-can-revert). ## What each entry shows - **Change**: the item (for example *Campaign: Summer sale*), what changed with the value before and after (for example a daily budget from $20.00 to $30.00), and the ad account with its platform. Ad text and keyword edits show each part that changed. - **By**: who or what made the change, and when. - **Status**: whether the ad platform applied it. - **Revert**, for an applied change you may revert. A change that failed shows the ad platform's reason in red under it. ## Statuses - **Pending**: Roasby sent the change and waits for the ad platform. The page updates on its own once it applies. - **Applied**: the ad platform made the change. - **Failed**: the ad platform refused it, with the reason. - **Reverted**: a later revert put the value before back. A [batch](/docs/safety-model#batches-many-items-in-one-change) shows as one entry: **Applied**, **Partly applied** or **Failed**. Open it to see each item. A batch is reverted only once it has finished. A campaign settings change the ad platform took only in part shows **Partly applied**, with the parts it refused and why. The parts it took can be reverted. An applied status, budget or bid change shows in Roasby at once. After a new campaign, Roasby usually syncs that ad account within a few minutes, so everything the platform made shows. ## Revert a change Anyone who may change ads (owners and admins, and members when the workspace allows it, see [Workspaces](/docs/workspaces#who-can-change-ads)) can revert an applied change: 1. Choose **Revert** on the change. 2. Read what the revert will do, and confirm. The revert is a new change in the log. It goes to the ad platform like any other change and is **Pending** until it applies. For a batch, **Revert batch** puts back every item the batch applied, as a new batch; you can still revert one item of a batch on its own. ### What a revert does - **A status, budget or bid**: puts the value before back. - **A new campaign, ad group, ad or keyword**: pauses it. Roasby never deletes anything. - **Added negative keywords**: takes away exactly the ones that change added; ones that were there before stay. Reverting that adds them again. - **Ad text**: writes the ad's old text back. The ad keeps its status, and the ad platform reviews the text again. - **A keyword edit**: puts the keyword back as it was. When the edit replaced the keyword, the new one is paused and the old one comes back. - **Campaign settings**: restores only the sections the change touched, such as countries or the ad schedule. - **Bidding and conversion goals**: puts the strategy, every target and the goals back as they were. One exception: Microsoft Ads doesn't take a max cost per click again after a strategy switch, so the strategy comes back without it (the preview says so). - **A new asset link**: pauses the link. On Microsoft Ads, which can't pause a link, the link is taken away; the asset stays. ### Guardrails on reverts A revert is checked by the same [guardrails](/docs/safety-model#budget-and-bid-guardrails) as any change, with one exception: a revert by a person skips the **max change per step**, because it restores a value the item already had. A revert by an AI assistant is held to the max change too. So some reverts only a person can make, on the web. For example, when a bidding target is now beyond a guardrail (the max bid, max target CPA or min target ROAS) or the max bid change, your assistant's revert is refused with `revert_past_guardrails`; your own revert on the **Change log** page restores the exact target the campaign had. ## What can't be reverted A revert is refused with the reason when: - the change isn't applied (`not_applied`); - it was already reverted (`already_reverted`). A revert the ad platform refused can be tried again; - the item changed again since (`changed_since`). Revert the newer change first; - there is nothing to take away, for example negative keywords that already existed (`nothing_to_revert`); - every item a batch added is still paused, so a revert would change nothing; - the campaign now uses bidding Roasby could not set back (`bidding_not_revertible`). The ad account's state counts too: - **Read-only: over the limit**: only a person can revert, on the web. Your assistant can't. - **Read-only: set by support**: every change is refused, reverts included. - **Disconnected**: its change log is deleted, so earlier changes can no longer be reverted from Roasby. ## Ask your AI assistant Your assistant reads the log with `list_ad_changes` (one ad account with `ad_account_id`; one campaign, everything in it and the change that created it, with `campaign_id`; days with `from` and `to`; a batch's items with `batch_id`). It reverts a change like any other change, with a preview you confirm: - one change: `preview_revert_ad_change`, then `revert_ad_change`; - a batch: `preview_revert_ad_change_batch`, then `revert_ad_change_batch`. Try *"What did you change in my Google Ads account today?"*, *"Which changes failed this week, and why?"* or *"Revert yesterday's budget change on the Summer sale campaign."* ## Limitations - A change can be reverted once (a revert the ad platform refused can be tried again), and only while the item still has the value it set. - An AI assistant's revert keeps the max change per step; a person's revert on the web doesn't. - Reverting never deletes: new items are paused, and only negative keywords, targeting and (on Microsoft Ads) asset links a Roasby change added are taken away. - The log shows changes made through Roasby only. Changes made in the ad platform itself show in Roasby after the next sync, but not in the log. See every limit by platform on [Limitations](/docs/limitations). --- # Ad accounts > Connect Google Ads, Microsoft Ads and ChatGPT Ads, including manager accounts, keep them in sync and control who manages connections. Open **Ad accounts** under **Manage** in the sidebar. One table shows every login you connected, with its platform and its ad accounts listed under it (status, guardrails and last sync). **Add ad account** at the top right lists the platforms you can connect. ## What you can do on each platform | | Google Ads | Microsoft Ads | ChatGPT Ads | | --- | --- | --- | --- | | Connect with | Google sign-in | Microsoft sign-in | An API key per ad account | | See performance, campaigns, ad groups and ads | Yes | Yes | Yes | | Keywords and search terms | Yes | Yes | No (ChatGPT Ads has none) | | Pause, enable and change daily budgets | Yes | Yes | Yes | | Change max bids | Ad groups and keywords | Ad groups and keywords | Ad groups | | Add negative keywords | Yes | Yes | No | | Create paused campaigns through your AI assistant | Search campaigns | Search campaigns | ChatGPT Ads campaigns | | See how conversions are tracked | Conversion actions and goals | Conversion goals | No | ## Connecting When you connect a platform, you sign in to it and approve Roasby's access (for ChatGPT Ads, you paste an API key). Roasby keeps that access **encrypted**, never shows it to anyone (not on the page, not to your AI assistant) and uses it only to read your accounts and make the changes you ask for. Owners and admins can connect platforms. ### Connect Google Ads 1. On **Ad accounts**, select **Add ad account**, then **Connect** next to Google Ads. 2. Pick your Google account and allow Roasby to **manage your Google Ads campaigns**. Leave that box ticked: without it, Roasby cannot read or change your accounts. 3. Pick the ad accounts to connect. You see every account your Google login reaches, including client accounts under a **manager account (MCC)**, shown "via" the manager's name. Manager accounts themselves (they have no campaigns) and cancelled or suspended accounts are not listed. 4. Select **Connect selected accounts**. The page shows how many places your workspace has left. The first sync starts right away. If the picker says some accounts may be missing (a login with very many accounts), connect the ones shown, then connect the same login again for the rest. If Google refuses to list your accounts, the picker shows Google's reason. Accounts you leave out are not touched. To add them later, connect the same login again and tick them. ### Connect Microsoft Ads 1. On **Ad accounts**, select **Add ad account**, then **Connect** next to Microsoft Ads. 2. Sign in with a personal Microsoft account or a work or school account, and allow Roasby to **manage your Microsoft Advertising accounts**. 3. Pick the ad accounts to connect. You see every active account your login can use, including accounts an agency's **manager account** manages for a client, shown "via" the manager account. Accounts that are not active (draft, pending, suspended or closed) and Smart campaigns accounts are not listed. 4. Select **Connect selected accounts**. The first sync starts right away; for a large account it can take a few minutes. If Roasby says your login has no active Microsoft Advertising account, sign in once at [ads.microsoft.com](https://ads.microsoft.com) with the same login (or use the login that manages your ads), then connect again. ### Connect ChatGPT Ads Each ChatGPT Ads account has its own **API key**, which connects that one account. 1. In [ChatGPT Ads Manager](https://ads.openai.com), open **Settings**, create an API key for the ad account and copy it. 2. On **Ad accounts** in Roasby, select **Add ad account**, then **Connect** next to ChatGPT Ads, paste the key and select **Connect**. Roasby checks the key and connects its ad account; the first sync starts right away. 3. To connect another ChatGPT Ads account, create a key in that account and connect it the same way. Roasby never shows the key again, to anyone. ChatGPT Ads reports conversion value only when purchase tracking is set up in the ad account. Until its first attributed sale, its value and ROAS show as n/a and its spend is left out of the combined ROAS. ### Connecting again Connecting a login that is still connected, for example to add accounts, keeps the accounts you leave ticked, with their history. **An account you untick is removed and its data in Roasby is permanently deleted**, as when you disconnect it. Nothing changes on the ad platform. Accounts the picker doesn't list stay connected. If an ad account is already connected through another login in the workspace, the picker says so; picking it moves it to the login you are connecting. ### Reconnect needed A connection shows **Reconnect needed** when Roasby's access ends, for example when: - you remove Roasby in your Google or Microsoft account settings; - you change your password; - you delete the ChatGPT Ads API key; - the person who connected the login leaves the workspace, is removed from it or deletes their account. This happens at once, and the confirmation lists the ad accounts affected. Its ad accounts stop syncing and become read-only until you fix it, but still count toward your workspace's limit. Select **Reconnect** and sign in again (for ChatGPT Ads, paste a new key of the same account). An owner or admin can reconnect with their own login. ## Syncing Roasby keeps your campaigns, ad groups, ads, keywords, daily performance and search terms up to date, so the dashboard, reports and your AI assistant answer quickly. - When you connect, Roasby brings in your accounts and at least the **last 30 days** of performance, or more depending on your workspace. - After that, each ad account syncs on a schedule: once a day or more often, depending on your workspace. On paid plans, Microsoft Ads and ChatGPT Ads accounts sync every hour (Google Ads accounts every 6 to 12 hours, because Roasby shares Google's daily request limit with every customer). Each sync also refreshes the last few days, because platforms keep adding late conversions. - On Google Ads, a scheduled sync asks Google which campaigns, budgets, settings, ad groups and assets changed since the last sync and reads only those again (ads, keywords and numbers every time). The whole account is read at least once a day. - Changes you make in Google Ads or Google Ads Editor show after the next sync. One made in the last few minutes before a sync shows with the one after. - Microsoft Ads and ChatGPT Ads are read whole on every sync. - Each ad account shows when it was **last synced**. - **Sync now** on an ad account syncs it right away and reads the whole account, its conversion goals included. Any member can use it: on Microsoft Ads and ChatGPT Ads every 5 minutes, on Google Ads as often as your workspace allows (from once a day to every 15 minutes); the button shows when it is available again. While a sync of the account is already on its way, **Sync now** says so instead. - Changes made through Roasby (by you or your AI assistant) show without **Sync now**. A paused item, a new budget or a new bid shows as soon as the change applies. An accepted edit (ad text, a keyword, settings, bidding or goals) shows the same way. After a new campaign, ad group, keyword, ad or asset, Roasby syncs that ad account on its own about a minute and a half later, so everything the platform made shows, and reads its conversion goals again so the campaign can get campaign goals, a target CPA or a target ROAS (at most once every 5 minutes and 24 times a day per account). After negative keywords, it reads the account's negative keywords again. This doesn't use your **Sync now** allowance. It is skipped while Roasby's shared Google Ads capacity is busy; the scheduled sync then brings the campaign in. - In workspaces that sync only while they are used, a workspace that nobody opens (and where no AI assistant uses Roasby) for **14 days** pauses its syncs. They start again when you come back. Syncing never changes anything in your ad accounts. Items removed on the platform stay in Roasby with their history. ## Conversions Ask your AI assistant how an ad account tracks conversions: what bidding aims for and the problems Roasby found. See [Conversions](/docs/conversions). ## Disconnecting **Disconnect** on a connection: - removes Roasby's access right away and asks Google to revoke it too (unless another of your workspaces still uses the same Google login); - stops syncing its ad accounts and removes them from Roasby straight after you confirm; - **permanently deletes** their campaigns, performance history, search terms, recommendations, alerts and change log. Changes already made can no longer be reverted from Roasby. Weekly reports already sent keep their totals. A login with an account that support set read-only can't be disconnected until support lifts it. Microsoft and ChatGPT Ads don't let apps revoke their own access. To end it there too: - **Microsoft Ads:** remove Roasby at [account.microsoft.com](https://account.microsoft.com/privacy/app-access) (**Privacy** → **Apps and services**) for a personal account, or ask your organization's admin for a work account. - **ChatGPT Ads:** delete the key in ChatGPT Ads Manager → **Settings**. Nothing changes in your ad accounts themselves. Connecting the same login later starts fresh: Roasby syncs the accounts again, as far back as your workspace's history allows. Deleting a workspace disconnects its connections the same way, and so does deleting your Roasby account for your personal workspace and for workspaces deleted with it. Logins you connected in other workspaces need reconnecting by someone else, and their data stays. ## Limits on ad accounts and members Each workspace has a set number of **active** ad accounts and members. When you reach a limit, connecting another ad account or inviting another person is refused with a short message; nothing is replaced or removed. If a workspace has more ad accounts than it allows (for example after its limit changes), nothing is disconnected or deleted. The oldest ones stay active and the others become **read-only: over the limit**: they keep their data, stop syncing and cannot be changed, though you can still revert earlier changes. Owners and admins choose which accounts stay active with **Make active**, picking an active account to swap with. Some workspaces have a monthly allowance of ad changes (for example 20 per calendar month). Reverts and changes the platform refused don't count. The owner gets an email at 80% and at 100%. Reports, previews and reverts always keep working. ### Read-only set by support Roasby support can make an ad account read-only, for example during a payment dispute or at your request. It shows **Read-only: set by support**: it keeps syncing and its reports keep working, but every change, reverts included, is refused until support allows changes again. Write to support@roasby.com to find out more. ## Guardrails and the change log Each ad account shows its guardrails: the max daily budget per campaign, the max bid, the max change per step for budgets and bids, and, optionally, a max target CPA and a min target ROAS for bidding targets. Owners and admins edit them with **Guardrails**. Every budget and bid change, by a person or an AI assistant, must stay within the guardrails. See the [safety model](/docs/safety-model). ### Right after you connect Roasby opens the money caps of each account new to the workspace in turn (accounts you reconnect keep theirs): its **max daily budget** and **max bid**, in the account's currency. - The max change per step for budgets and bids is filled in from your workspace's [safety defaults](/docs/safety-model#safety-defaults-for-new-ad-accounts). - Save them, or choose **Set later** to move on to the next account. - A new account has no max daily budget until you set one, and your AI assistant cannot create campaigns in it until then: choose **Set it to create campaigns** on the account, or use the link your assistant gives you. ### More on each account - If a sync fails, the account shows why under **Last synced**. - **Campaigns** on an account opens its [campaigns](/docs/campaigns). - **Change log** opens the changes made to it (see [Change log](/docs/change-log)). ## Who can do what | Role | View ad accounts, campaigns and the change log, and Sync now | Connect, disconnect, set guardrails and Make active | Pause, enable, change budgets and bids, and revert | | --- | --- | --- | --- | | Owner | Yes | Yes | Yes | | Admin | Yes | Yes | Yes | | Member | Yes | No | Only when the workspace allows it | ## Ask your AI assistant Your assistant works with ad accounts through these tools: - `list_ad_accounts`: the workspace's ad accounts with platform, name, account ID, currency, time zone, status (including `needs_reconnect` and `locked_by_support`), last sync and guardrails. - `list_conversion_actions` (with `primary_only` or `include_removed`): how each account tracks conversions (see [Conversions](/docs/conversions)). - `list_ad_changes`: the change log. - `run_ad_account_sync`: syncs an account. - `preview_activate_ad_account` and `activate_ad_account`: for owners and admins, swaps which accounts are active, after you confirm. Try *"Which ad accounts are in my Roasby workspace?"*, *"Is conversion tracking working in my Google Ads account?"* or *"Sync my Microsoft Ads account now."* Connecting, disconnecting and setting guardrails happen only in Roasby, never through your assistant. Never paste an API key into a chat. ## Limitations - Connecting, disconnecting and setting guardrails happen only in Roasby on the web, never through your AI assistant. - Roasby works from a synced copy of each ad account: numbers are as fresh as its last sync. Roasby's own changes show without it (a new campaign through a sync a few minutes later); for fresh numbers, or changes made in the ad platform itself, use **Sync now**. - Disconnecting permanently deletes the account's data in Roasby, and changes made before can no longer be reverted from Roasby. - Microsoft Ads and ChatGPT Ads don't let Roasby end its own access: remove it there as described under [Disconnecting](#disconnecting). - Conversion tracking is read only, every few hours (and with **Sync now**): Roasby never creates or changes conversion actions, goals or Google Analytics 4 key events, and doesn't read ChatGPT Ads conversion tracking. Google Ads gives no tag status, so Roasby judges recording by the last conversion (when Google Ads received it, or for Google Analytics 4 imports its day; none in 7 days is **No recent conversions**). See [Conversions](/docs/conversions). - A read-only account (reconnect needed, over the limit or set by support) can't be changed through your assistant; your assistant tells you what to do and where. See every limit by platform on [Limitations](/docs/limitations). --- # Workspaces > Create workspaces, invite people, choose their roles, decide whether members may change ads, and switch between workspaces. A **workspace** holds ad accounts and the people who work on them. Everything in Roasby belongs to one workspace: its ad accounts, campaigns, recommendations, alerts, reports and change log. Nobody outside the workspace sees any of it. You can belong to several workspaces, for example your own and a client's. ## Your personal workspace Every Roasby account starts with a **personal workspace**, ready right after you sign up. You are its owner. - You can invite people to it. - You can't leave it or delete it on its own: it is deleted with your Roasby account (see [Delete your account](/docs/account-settings#delete-your-account)). ## Create a workspace Open the workspace menu at the top of the sidebar and choose **New workspace**, or choose **New workspace** on the **Workspaces** page. Give it a name. You become its owner, and Roasby switches you to it. ## Switch workspaces The workspace menu at the top of the sidebar lists every workspace you belong to. Pick one to switch to it. The workspace you last opened is your **current workspace**: the one your AI assistant works in unless you name another. ## Workspace settings Open **Workspace settings** under **Manage** in the sidebar. It has: - **General**: the workspace name. - **Members**: the people in the workspace, their roles and the invitations still pending. - **Ad changes**: **Allow members to change ads** (shared workspaces only). - **Safety defaults**: the max budget and bid change per step that every new ad account starts with (see [safety defaults](/docs/safety-model#safety-defaults-for-new-ad-accounts)). - **Delete workspace** (not for a personal workspace). ## Roles Each person in a workspace has one role. | Role | What they can do | | --- | --- | | **Owner** | Everything: rename the workspace, invite people, change roles, remove members, connect ad accounts, set guardrails, manage [billing](/docs/billing) and delete the workspace. Each workspace has exactly one owner. | | **Admin** | Rename the workspace, invite people and cancel invitations, connect and disconnect ad accounts, set guardrails and safety defaults, and turn **Allow members to change ads** on or off. Admins always change ads. | | **Member** | Read everything: dashboard, campaigns, search terms, recommendations, alerts, reports and the change log. Members change ads only when the workspace allows it. | Only the owner changes roles and removes members. The owner's own role can't be changed, and the owner can't be removed or leave. ## Who can change ads Owners and admins can always change ads: pause and enable, change budgets and bids, approve recommendations and revert changes, on the web and through their AI assistant. Members only read, unless an owner or admin turns on **Allow members to change ads** under **Workspace settings → Ad changes**. Then members can pause and enable ads, change campaign budgets and bids, and revert changes, on the web and through their AI assistant. Every switch of that setting is recorded. Guardrails, ad platform connections and the setting itself always stay with owners and admins. See [Who can change ads](/docs/safety-model#who-can-change-ads). ## Invite people 1. On **Workspace settings**, choose **Invite member**. 2. Enter their **Email address** and choose a **Role** (admin or member). 3. Choose **Send invitation**. Roasby emails them a link. The person signs in, or registers with that email, to join. Invitations waiting for them show as **Pending workspace invitations**, where they choose **Accept** or **Decline**. Accepting switches them to the new workspace. - An invitation expires after a few days (3 by default). Send a new one if it ran out. - **Cancel invitation** on a pending invitation takes it back. - A workspace has a set number of members, and pending invitations count toward it. When it is full, a new invitation is refused with a short message (see [Limits on ad accounts and members](/docs/ad-accounts#limits-on-ad-accounts-and-members)). ## Remove someone or leave - **Remove member**: the owner removes someone from **Workspace settings**. - **Leave workspace**: anyone but the owner leaves a workspace from the **Workspaces** page. You can't leave your personal workspace. When someone leaves or is removed, the ad platform logins they connected in that workspace are disconnected at once, and its ad accounts show **Reconnect needed**. The confirmation lists the ad accounts affected. An owner or admin can reconnect them with their own login (see [Reconnect needed](/docs/ad-accounts#reconnect-needed)). ## Delete a workspace The owner chooses **Delete workspace** in **Workspace settings** and types the workspace name to confirm. This can't be undone: - its ad platform connections are disconnected, and its ad accounts and their data in Roasby are deleted; - its members and invitations are removed, and anyone working in it is moved to their personal workspace. Nothing changes in the ad accounts themselves. A workspace that still pays for Roasby can't be deleted until that ends (see [Billing](/docs/billing)). A personal workspace is deleted only with your Roasby account. ## Demo workspaces A **demo workspace** holds sample ad accounts and data. Nothing in it reaches a real ad platform, so you can try changes safely. - It can't connect or disconnect real ad accounts. Create a workspace of your own to connect yours. - Its billing is turned off. - Your assistant tells you when it works in a demo workspace. ## Work in another workspace through your assistant One connection reaches every workspace you belong to. Your assistant works in your current workspace (the one you last opened in Roasby) unless you name another one. - Ask *"Which Roasby workspaces can you see?"* Your assistant calls `list_workspaces`: each workspace's name, your role, whether you may change its ads and how many ad accounts it has. Demo workspaces are marked, and your assistant tells you when it works in one. - Then say which one you mean: *"Show me last week's spend in the Client A workspace."* Your assistant passes that workspace's `workspace_id` to every tool it calls. - Your role counts in each workspace: you may change ads in one workspace and only read in another. - A change you confirmed in one workspace can't be made in another: your assistant previews it again there. - Working in another workspace through your assistant doesn't change the workspace you see in Roasby. ## Ask your AI assistant - `get_current_workspace` returns the workspace your assistant acts in: its name, your role, whether you may change its ads (`can_change_ads`), whether members may (`members_can_change_ads`), and its safety defaults. - `get_workspace_members` lists the people in it with their roles, and the pending invitations. - `list_workspaces` lists every workspace you belong to, with the `workspace_id` other tools take. Try *"Which Roasby workspace am I in, and can I change its ads?"*, *"Who is in my Roasby workspace?"* or *"Which workspaces can you see?"* ## Limitations - Creating workspaces, inviting people, changing roles, removing members and **Allow members to change ads** are done in Roasby on the web, never through your AI assistant. - A connection reaches every workspace you belong to. You can't limit it to some: to keep an assistant out of one, leave that workspace or disconnect the assistant on the **AI connections** page. - Your assistant works in your current workspace unless you name another, and never changes the workspace you see in Roasby. - The owner can't leave a workspace or hand it over. Ownership passes to the admin who joined first only when the owner deletes their Roasby account. See every limit by platform on [Limitations](/docs/limitations). --- # Account settings > Change your name, language, email preferences and password, connect Google sign-in, set up two-factor or passkeys, and delete your account. Open the menu under your name at the bottom of the sidebar and choose **Settings**. All your account settings are on that one page. These settings belong to you, not to a workspace. For workspace members, roles and invitations, open **Workspace settings** under **Manage** in the sidebar (see [Workspaces](/docs/workspaces)). ## Profile Change your name and the **language** Roasby shows you. Your **email address** is how you sign in, so it can't be changed. The page shows whether it is verified. ## Emails You first choose these emails when you set up a new workspace, and can change them here any time. Every Monday you get the [weekly report](/docs/weekly-report) of each workspace you are in. Set **Weekly report emails** to **Off** to stop them for all your workspaces (the unsubscribe link in each report does the same), and to **On** to get them again. The reports stay on each workspace's Reports page. If you own or administer a workspace, you also get an email when Roasby finds something unusual in its ad accounts (see [alerts](/docs/alerts)). Set **Alert emails** to **Off** to stop those for all your workspaces, and to **On** to get new ones again. Alerts found while the emails were off are not sent later unless they get worse or come back; they stay on each workspace's Alerts page. ## Sign-in and security - **Password:** choose **Change password** and enter your current password, then the new one. If you signed up with Google, choose **Set a password** so you can also sign in with your email. Changing or resetting your password signs you out in your other browsers and devices; connected AI apps stay connected. The exception is the first password on an account that had none: your other browsers and devices stay signed in until their sessions time out. - **Google sign-in:** **Connect Google** to sign in with your Google account; Google asks which account to use. A Google account can only be connected to one Roasby account. **Disconnect** stops signing in with it; set a password first, so you can still sign in. - **Two-factor authentication:** **Turn on** asks for a code from an authenticator app each time you sign in. Once it is on, open **Recovery codes** and save them somewhere safe; each one works once if you lose your phone. - **Passkeys:** **Add passkey** to sign in with your device's fingerprint, face or PIN, and remove the ones you no longer use. ### Confirm it's you Connecting or disconnecting Google, turning two-factor on or off, showing recovery codes, and adding or removing a passkey first ask you to **confirm it's you**. Use one of: - your password; - a passkey; - **Email me a code**: a 6-digit code that works once, for 10 minutes; - if two-factor authentication is on, **Use your authenticator app** instead of the emailed code (or one of your recovery codes if you lost your phone). Once you have confirmed, Roasby doesn't ask again for a few hours. ## Delete your account Choose **Delete account** and enter your password (if you have no password, confirm it's you first). Deleting your account cannot be undone. The dialog shows what happens to each workspace you own: - **Your personal workspace** is deleted with its ad accounts and data. Anyone you invited to it loses access. - **A workspace with an admin** passes to the admin who joined first. They become the owner and get an email. - **A workspace with nobody else** is deleted with its ad accounts and data. - **A workspace with only members** stops the deletion: make one of them an admin, or remove them, then try again. - **A workspace with a running subscription** also stops it: cancel the subscription in **Billing** first. Ad platform logins you connected in workspaces that carry on show **Reconnect needed**, and their data stays. ## AI connections The AI assistants connected to your account (Claude, ChatGPT, Codex, Cursor...) have their own page, **AI connections**, under **Manage** in the sidebar. See [Connect your AI](/docs/connect-your-ai#disconnect-an-assistant). These settings are only available on the web. AI assistants cannot change how you sign in or disconnect other assistants. ## Limitations - Account settings, sign-in methods and AI connections are changed on the web only, never through your AI assistant. See every limit by platform on [Limitations](/docs/limitations). --- # Billing > How a workspace pays for Roasby, how to change or cancel its subscription, and what happens after a failed payment. A Roasby **workspace** pays, not a person. The price depends on how many ad accounts the workspace connects, never on your ad spend and never on how many questions you or your AI assistant ask. See the current prices on the [pricing page](/pricing). Open **Billing** (under **Manage** in the sidebar of your workspace) to see the current plan, whether it is billed monthly or yearly, and the usage: active ad accounts, members (pending invitations included) and, when the workspace has a monthly allowance, this month's ad changes. Every member can see this page; only the workspace **owner** can buy, change or cancel a subscription. Each plan also sets how many items one batch change can have: pausing or enabling many campaigns, ad groups, ads or keywords together counts as one change, with up to 100 items on Free, 1,000 on Starter, 5,000 on Pro and 10,000 on Agency. When your assistant adds ad groups, each ad group, keyword, negative keyword and ad counts as one item, and a new search campaign counts the campaign and every part of it the same way (it is still one change). Split larger ones into several batches, or create a large campaign in parts. ## Subscribing Select **Change plan** on the Billing page to see the plans, monthly or yearly when both are offered, and choose one. **Compare all plans** opens the full comparison on the pricing page. Payment happens on Stripe Checkout, a page hosted by Stripe: Roasby never sees your card number. Checkout asks for a billing address so the right tax can be added, and businesses can enter a tax ID (for example an EU VAT number for reverse charge). Prices are shown without tax. If you have a promotion code, enter it on the Checkout page. After you pay, you come back to the Billing page, and the new limits apply as soon as Stripe confirms the payment. ## Changing plans, invoices and your card The owner opens **Manage billing** (or a plan's button under **Change plan** once subscribed) to use Stripe's billing portal. There you can: - move to a bigger plan: it applies at once and you pay the difference for the rest of the period; - move to a smaller plan or another billing interval: it applies at the end of the current period; - update the card, the billing address and the tax ID; - download invoices and receipts; - cancel the subscription. ## Custom Agency prices (more than 30 ad accounts) The Agency plan includes 30 ad accounts. If you need more, [contact support](/support). Roasby makes a private price for your workspace and emails the owner a link to the Billing page, where a **Your custom Agency price** card shows the price and how many ad accounts it includes. Only the owner sees it. - Without a subscription, **Subscribe** opens Stripe Checkout at that price. - With a subscription, **Switch to this price** moves it to the custom price at once. Stripe charges or credits the difference for the rest of the period. The higher ad account limit applies while the workspace pays the custom price. ## Cancelling A cancelled subscription keeps working until the end of the period you paid for. The workspace then falls back to the free limits: nothing is disconnected or deleted. Ad accounts beyond the new limit become **read-only** (they keep their data, stop syncing and cannot be changed, but reverts still work), and you choose which ones stay active on the [Ad accounts](/docs/ad-accounts) page. After a downgrade or a cancellation, the longer performance history and change log are kept for a while before they are trimmed to the new limits, so you can come back without losing them. A workspace, or your Roasby account, cannot be deleted while it has a subscription. Cancel it first; once the subscription has ended you can delete the workspace. ## Failed payments When a payment fails, Stripe retries it over the next days and emails the owner. The workspace keeps its plan during a grace period, and the Billing page shows until when. Update the card in **Manage billing** to keep the plan; after the grace period the workspace falls back to the free limits as if it had cancelled. ## AI assistants and billing Billing happens on roasby.com only. Your AI assistant cannot see prices, start a checkout or change the subscription. When a workspace reaches a limit, the assistant gets a short neutral message, and the owner can review the plan here. ## Limitations - Billing happens on roasby.com only: your AI assistant can't see prices or change the subscription. See every limit by platform on [Limitations](/docs/limitations). --- # MCP tool reference > Every tool the Roasby MCP server offers AI assistants for Google Ads, Microsoft Ads and ChatGPT Ads, with its safety hints. These are the tools your AI assistant can call through the Roasby MCP server. **Read-only** tools never change anything. Tools that change your ad accounts follow the [safety model](/docs/safety-model). This list is always up to date. ## How changes work Every tool that changes something has a matching `preview_*` tool. - The preview checks the change without making it and returns a one-time confirmation token. - Your assistant is told to show you the change and ask you to confirm before it passes the token to the change tool. - See [Your assistant previews every change](/docs/safety-model#your-assistant-previews-every-change). When only a person can do something, a tool result lists it in `user_actions`. See [Limitations](/docs/mcp-tools#limitations) below. ### EU political ads declaration While a Google Ads campaign has no EU political ads declaration, the preview of any change in that account lists the campaigns to declare in `user_actions` (`declare_eu_political_ads`). Google Ads refuses changes until then. ## Workspaces Tools act in your current workspace in Roasby. See [Workspaces](/docs/workspaces). - `list_workspaces` lists every workspace you belong to: its ID, your role, `can_change_ads`, its number of ad accounts, and whether it is a demo workspace. - Every tool that works in a workspace takes an optional `workspace_id` to act in another one. Roasby checks that you belong to it on every call. - A confirmation token works only in the workspace of its preview. - `get_current_workspace` shows whether you may change ads in the workspace (`can_change_ads`). - `get_workspace_members` lists the people in the workspace (name, email and role) and the invitations that are still pending, one page at a time. ## Reading your accounts - `list_ad_accounts` lists the ad accounts in the workspace: platform, name, currency, time zone, status, whether it is still connected, its guardrails (with the optional `max_target_cpa_micros` and `min_target_roas_percent`), when Roasby last synced it, when it last read the conversion goals (`conversions_synced_at`), and whether the campaign settings read failed at the last sync (`settings_read_failing`). - `get_performance_summary` summarizes spend, conversion value, ROAS, conversions, clicks and impressions across platforms over the last 7, 30 or 90 complete days, with the period before for comparison, for every account or narrowed to one ad account (`ad_account_id`) or campaign (`campaign_id`), with a row for each day. Amounts are grouped per currency, never converted. - `list_ad_entities` finds the IDs of campaigns, ad groups, ads and keywords. `campaign_id` lists one campaign's ad groups, ads or keywords across its ad groups. An ad group under automated bidding has no `cpc_bid_micros` (the platform's placeholder is no bid you set). - `get_campaign_performance`, `get_search_terms` and `find_wasted_spend` read their results. `get_search_terms` adds `other_terms_cost`: the search campaigns' spend no reported search shows. ### Keyword insight `list_ad_entities` gives each keyword its `insight`: - The Quality Score and its three parts. - The first page, top of page and first position bid estimates, in micros and as money. - `below_first_page_bid`. - Its approval, serving and primary status, with the reasons. - A missing score or estimate comes with `quality_score_gap` or `estimates_gap`: - `not_enough_data` - `automated_bidding` - `not_reported_yet` `max_quality_score` and `below_first_page_bid` narrow the keywords. On other levels, only a null maximum and `false` are taken. ### Policy issues Each ad or keyword the platform disapproved, limited or is still reviewing has a `policy` object: - Its `state`, `review_status` (Google Ads) and `appeal_status` (Microsoft Ads). - Each finding in `issues`, with its `topic`, `category`, `label`, `type`, the `part` it is about and `where`, the `evidence`, the `countries` where it can't show, and `advice`. - The `user_actions` step in the ad platform, where reviews and appeals happen. `policy_issues_only` lists only the ads or keywords with a policy issue: disapproved, limited, or with a finding such as a prohibited headline. ### Impression share `get_campaign_performance`, and `list_ad_entities` with a `period` for campaigns and ad groups, give search campaigns an `impression_share`: - `search`, `lost_to_rank`, `lost_to_budget`, `top` and `absolute_top`. - `lost_to_budget`: Google Ads reports it for campaigns only, so a Google Ads ad group has none. - Each comes with: - a `value` from 0 to 1 - a `bound` (`below_10_percent` or `above_90_percent`) when the platform only reports that - its `clamped_days` - a `limit` (`below`: at most the value, `above`: at least it) - a `label` - Plus `days_with_data` and `missing_days`. ### Recommendations `list_recommendations` lists the changes Roasby suggests, each with the preview tool and arguments that approve it. See [Recommendations](/docs/recommendations). - A `raise_budget` names `preview_update_campaign_budget` with a budget within the guardrails. - When the guardrails leave no raise, it has no arguments, with `blocked_by` and `user_actions`. - `changed_since` while it waits for 14 days at a changed budget. - `preview_archive_recommendation` and `archive_recommendation` dismiss an open recommendation. Nothing changes in the ad account; Roasby just never suggests it again. ### Conversion actions and goals `list_conversion_actions` shows how each ad account tracks conversions. See [Conversions](/docs/conversions). - Every conversion action or Microsoft Ads conversion goal with its `source`, `status`, `category`, `goal`, `primary`, `counted_in_conversions`, `counting`, `attribution`, `shared`, `recording`, `last_received_at` and `recent_conversions` (the last 30 days). A campaign's Google Ads custom goal lists its actions in `custom_goal_conversion_action_ids`. - Per account: `readable`, `synced_at`, `bidding_goals` and `problems`. - `primary_only` and `include_removed` narrow or widen it. - Each account's `campaign_goals` lists the campaigns with goals of their own. `get_campaign_performance` gives each campaign its `conversion_goals`: - `level`, `custom_goal_name`, `bidding_goals` and `problems`. - Its Google Ads `goals` (each `key`, `label` and `biddable`). - Its Microsoft Ads `conversion_action_ids`. ### Alerts and the weekly report - `list_alerts` lists the [anomaly alerts](/docs/alerts): spend spikes, cost per conversion jumps and disapproved ads, each disapproved ad with its `policy`. - `get_weekly_report` gives the [weekly report](/docs/weekly-report) members get by email. ### Reading text assets `list_assets` lists the text assets linked in the workspace: sitelinks, callouts, structured snippets, prices and promotions. See [Assets](/docs/assets). - Each with the Roasby ID of its link (for pausing and enabling it), where it is linked (the whole ad account, a campaign or an ad group), its status and its content. - Whether a pause or enable of it is still being applied. - Narrow it with `ad_account_id`, `campaign_id` (the campaign and its ad groups), `ad_group_id`, `type` or `status`. Removed links are left out unless `include_removed` is true. - ChatGPT Ads has no such assets. ### Keyword research `get_keyword_ideas` and `get_keyword_volumes` ask the ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), in 1 to 10 countries and one language. See [Keyword research](/docs/keyword-research). - `get_keyword_ideas` starts from 1 to 20 seed keywords and/or a web page. - `get_keyword_volumes` reads exactly the keywords given (up to 1,000). Keywords that came back without a result are listed in `missing_keywords`. - Each keyword comes with its average monthly searches and monthly trend over the last 12 months, its competition and a bid estimate in the account currency, the most searched first. - A new request can take a few seconds and then answers with status `running`. The same request within a day is answered from Roasby's cache. ### Syncing Roasby reads from its own copy of your data. `run_ad_account_sync` asks Roasby to refresh one ad account's copy now, instead of waiting for the scheduled sync. - It only reads from the platform and never changes ads. - The sync runs in the background and usually takes a few minutes. `last_synced_at` on the ad account changes when it finishes, and `last_sync_error` is set when it fails. - It also reads the conversion goals again, so a new campaign can get its goals and targets. - It isn't needed after a change made through Roasby: applied changes are in Roasby's copy at once, and after new campaigns, ad groups, keywords, ads or assets Roasby syncs the account by itself a few minutes later (`follow_up_sync_due_at` in `list_ad_accounts`). - Each account can be synced this way only so often: Microsoft Ads and ChatGPT Ads accounts every 5 minutes, Google Ads accounts from once a day to every 15 minutes, by workspace. When it is too soon, or a sync is already on its way, `started` is false and `next_sync_allowed_at` says when. ## Single changes Each of these changes one item, and the change is logged and can be reverted. It is pending until the ad platform applies it. - `preview_pause_entity` and `pause_entity` pause a campaign, ad group, ad, keyword or asset link. - `preview_enable_entity` and `enable_entity` enable (resume) one. Enabling can start spending money, so a campaign above the ad account's max daily budget, or only partly created, is refused. - `preview_update_campaign_budget` and `update_campaign_budget` set a campaign's daily budget, within the ad account's guardrails. - `preview_update_bid` and `update_bid` set the max cost per click of an ad group or keyword, within the guardrails. Only items with `bids_adjustable` true can change: campaigns under automated bidding ignore these bids. - `preview_add_negative_keywords` and `add_negative_keywords` exclude keywords from a campaign or an ad group. Negative keywords it already has are left as they are, and reverting takes away exactly the ones added. See [Search terms](/docs/search-terms). ### Suspended ad accounts An ad account beyond the limit of active ad accounts of the workspace is suspended: read-only history. See [Ad accounts](/docs/ad-accounts). - `preview_activate_ad_account` and `activate_ad_account` make a suspended ad account active again (synced and changeable). Owners and admins only. - When the workspace is at its limit, `replace_ad_account_id` names the active account that becomes read-only in its place. - Nothing is disconnected or deleted, and the swap can be made again the other way. ## Many items at once ### Pause and enable - `preview_pause_entities` and `preview_enable_entities` check many campaigns, ad groups, ads, keywords and asset links of one ad account at once, and return one confirmation token for the items that pass. - `pause_entities` and `enable_entities` change them as one batch. - `list_ad_changes` shows the batch as one entry (`batch_id` lists its items, and `status` narrows them, for example to the failed ones). - `preview_revert_ad_change_batch` and `revert_ad_change_batch` undo it. ### Bulk bids `preview_update_bids` checks the max bids of many ad groups and keywords of one ad account at once, each against the same guardrails as `preview_update_bid`. `update_bids` changes them as one batch. Give them either: - `bids`: an amount per item, or - `entity_ids` (or every keyword of an `ad_group_id` or `campaign_id`, removed ones left out) with one `rule`: - `set` an amount - `change_percent` by a whole percent, rounded toward the current bid - `first_page_cpc` up to `cap_micros` With `limit_to_guardrails`, a bid beyond the max bid change per step or the max bid moves only as far as they allow: - It is marked `limited` (with `limited_by` and `requested_micros`), and `limited_count` says how many. - The preview and the result give a `next_step` (`bids` with the bids asked for, as absolute amounts, and `limit_to_guardrails`) for the bids the max bid change limited, so a later batch converges on them. `first_page_cpc` outcomes: - `no_first_page_estimate`: the keyword has no estimate (why in `detail`). - `first_page_cpc_keywords_only`: ad groups can't use it. - `no_change`: keywords at or above it are left as they are. ## Adding keywords, ad groups and ads See [Editing campaigns](/docs/editing-campaigns). ### New keywords - `preview_add_keywords` checks keywords to add to an existing ad group of a Google Ads or Microsoft Ads search campaign (text, match type, optional bid and final URL), each on its own. - `add_keywords` adds the ones that pass as one batch, every keyword paused. - `preview_enable_entities` enables them when you want. ### Ad groups - `preview_add_ad_groups` checks ad groups to add to an existing Google Ads or Microsoft Ads search campaign: a name, a default bid, and optionally keywords, negative keywords and up to 3 responsive search ads. - Each ad group is checked with all its parts, naming the part that breaks a rule (`detail`). - `add_ad_groups` adds the ones that pass as one batch, every ad group paused with its keywords and ads under it. ### Responsive search ads - `preview_add_responsive_search_ads` checks responsive search ads to add to existing ad groups of Google Ads or Microsoft Ads search campaigns in one ad account, each on its own, naming the part that breaks a rule. - `add_responsive_search_ads` adds the ones that pass as one batch, every ad paused. ### The shape of a new ad Every new ad has the same shape: - A `final_url`. - 3 to 15 `headlines` and 2 to 4 `descriptions`, each an object of `text` and an optional `pinned_position` (headlines 1 to 3, descriptions 1 to 2). - Optional `path1` and `path2`. - For an ad added to an ad group or a new ad group's ad, an optional `final_url_suffix`. Characters of Chinese, Japanese and Korean and emoji count as two toward the limits. ## Text assets `preview_add_assets` checks text assets (sitelinks, callouts, structured snippets, prices and promotions) to add to an ad account, a search campaign or one of its ad groups, or to several campaigns or ad groups of one ad account at once (`campaign_ids` or `ad_group_ids`, every asset to each). See [Assets](/docs/assets). - It names the refused ones with why: too long, too few values or rows, an asset that is there already, a Microsoft Ads campaign or ad group that is not paused, and so on. - On Google Ads each asset is linked paused. Microsoft Ads has no paused links, so there Roasby links only to paused campaigns and ad groups. - `add_assets` adds the ones that pass as one batch. Assets are pending until the ad platform adds them. - Reverting an asset pauses its link, or on Microsoft Ads takes it away; the asset itself stays. - The pause and enable tools (`preview_pause_entities`, `preview_enable_entities` and the single-item ones) also take asset links. ## Creating campaigns `create_search_campaign` (Google Ads and Microsoft Ads) and `create_chat_campaign` (ChatGPT Ads) always create campaigns paused. See [Creating campaigns](/docs/creating-campaigns). A new search campaign is one blueprint: - Its own `negative_keywords` and its `ad_groups`, each shaped like an ad group of `add_ad_groups`. - It is checked as a whole: if any part breaks a rule, nothing is created and the preview names every such part with its path. - Every part counts toward the items of one change, and the campaign must fit 10,000 operations (`campaign_too_large`: create part of its ad groups, then add the rest with `add_ad_groups`). - Roasby takes no file: your assistant reads yours and fills the blueprint. It takes: - Any number of countries, and who sees the ads there (`location_option`). - Search partners. - `languages` on Microsoft Ads. Google Ads matches languages itself, so there they are only noted. - A `final_url_suffix` and a `tracking_url_template`. ## Campaign settings `preview_update_campaign_settings` checks a settings change of one Google Ads or Microsoft Ads search campaign, each section before and after in `details`. `update_campaign_settings` makes it as one change. See [Editing campaigns](/docs/editing-campaigns). ### Sections - `countries`: the whole set. `locations_not_only_countries` refuses it for a campaign that also targets regions, cities or a radius. - `location_option`. - `search_partners`. - `final_url_suffix` and `tracking_url_template`: null clears one. - `ad_schedule`: the whole schedule of `day`, `start`, `end` and `bid_adjustment_percent`. Empty runs all day. Refusals: `too_many_schedule_slots`, `schedule_slots_overlap`. - `device_bid_modifiers`: a percent per device, -100 for no ads. Refusal: `bid_adjustment_out_of_range`. - `ad_rotation`. - `languages`: Microsoft Ads only (`no_language_targeting` on Google Ads). ### Bid adjustments Bid adjustments are checked for each device in each quarter hour that shows ads: - The device multiplier times the hour's multiplier may rise at most the max bid change per step from what that pair had before. - A device or hours that showed no ads count as 0% and get no rise in that step. No schedule is every hour at 0%. - Otherwise the change is refused (`bid_change_too_large`, naming the device and hours). - With `limit_to_guardrails`, it is lowered to the largest step, with a `next_step` (taking a schedule away may wait for it). ### Other refusals and syncing - `no_ad_groups_to_set`: refuses the ad rotation (and Microsoft Ads search partners) for a campaign without synced ad groups. - A section changed in the ad platform since Roasby last read it is not sent. The change log names it in its refusal reason, and Roasby syncs the account again. - `list_ad_entities` gives each search campaign its current `settings` (with the schedule's `time_zone`). `settings_not_synced` means Roasby hasn't read them yet. ## Conversion goals `preview_update_conversion_goals` checks a change of what a Google Ads or Microsoft Ads search campaign bids on. `update_conversion_goals` makes it. See [Bidding and goals](/docs/bidding-and-goals). - `level` `account`: the ad account's goals. - `level` `campaign`, with `goal_keys` (Google Ads goal keys) or `conversion_action_ids` (Microsoft Ads). - Its `details` name each chosen goal that is not recording, and say that the learning period restarts. - Reverting puts back the exact setup before. Goals that record nothing, under bidding toward conversions, are allowed: the preview names each action that is not recording. Refusals: - `conversion_goals_not_synced` - `unknown_conversion_goal` - `no_conversion_goals_chosen` - `goals_not_on_campaign_type` - `account_goals_not_supported`: a Microsoft Ads campaign moving to or from the account's goals. ## Bidding `preview_update_bidding` checks a change of how a Google Ads or Microsoft Ads search campaign bids. `update_bidding` makes it. See [Bidding and goals](/docs/bidding-and-goals). ### What you can change - `campaign_id` with a `strategy`, and `limit_to_guardrails`: - `manual_cpc` - `maximize_clicks` - `maximize_conversions`, with an optional `target_cpa_micros` - `maximize_conversion_value`, with an optional `target_roas_percent` - `target_impression_share`, with `impression_share_location`, `impression_share_percent` and `max_cpc_micros` - Or a Google Ads `ad_group_id` with its own `target_cpa_micros`. Null takes it away. A new one needs a campaign that maximizes conversions with a target CPA and its own strategy. Maximize clicks keeps a max cost per click the campaign has. ### What the preview says Its `details` say that automated bidding sets the bids itself, and describe the learning period, a strategy without a target and the guardrails. A guardrail holds only once a person sets it. Bidding toward conversions that are not recording, or toward conversion value with none seen, is allowed with a warning line. - `target_above_max_bid`: a ceiling above the max bid. - `target_above_max_target_cpa`: a target CPA above the account's max target CPA. - `target_below_min_target_roas`: a target ROAS below the account's min target ROAS. - `target_change_too_large`: measured from the most recent target Roasby set or took away when the campaign has none now. With `limit_to_guardrails`, a `bidding_next_step`. - `impression_share_incomplete`: without a location, share or ceiling. ### Refusals - `bidding_not_revertible`: bidding Roasby could not put back. - `bidding_not_synced`: unread bidding. - `ad_group_target_cpa_not_supported`: ad group targets on Microsoft Ads, or without a campaign target CPA. - `target_removal_not_supported`: on Microsoft Ads, a target CPA or ROAS added to or taken from a campaign that keeps its strategy. - `impression_share_not_supported`: target impression share on Microsoft Ads. ### Reading and reverting bidding - `list_ad_entities` gives each campaign its `bidding` (`strategy`, targets, `portfolio`, `changeable`, `label`) and `has_pending_bidding_change`, and each ad group its `target_cpa_micros`. - An ad group's pending target CPA shows as its `has_pending_bid_change`. - While bidding is automated, bid changes are refused. - Reverting restores the exact bidding before, except a Microsoft Ads max cost per click after a strategy switch: Microsoft doesn't take it again, so the revert comes back without it (the preview says so). - Your assistant's revert keeps the guardrails and the max bid change per step (`revert_past_guardrails`). You can revert on the **Change log** page, which restores the exact earlier target. ## Ad text `preview_update_ads` checks edits of the text of Google Ads and Microsoft Ads responsive search ads in place. `update_ads` makes the edits as one batch. See [Editing campaigns](/docs/editing-campaigns). ### Two ways to edit - `ads`, each with its `ad_id` and only the parts that change: - `headlines` or `descriptions`, each list whole with its pins - `path1`, `path2` (null takes one away) - `final_url` - A literal find and replace: `find`, `replace`, and the scope: `ad_account_id`, `campaign_id`, `ad_group_id` or `ad_ids` (a campaign, ad group or ads need no `ad_account_id`), `fields` (`headlines`, `descriptions`, `paths`, `final_url`) and `match_case`. Ads without a match, and edits that change nothing, are left out. ### Checks - Each new text passes the rules of every new ad. None may be empty (`empty_ad_text`). - An ad that breaks one is refused on its own, with `detail`. - Each item has `ad_text` with the whole text `before` and `after`, and each part's `changes`. - Only responsive search ads whose text Roasby read can be edited (`ad_type_not_editable`, `ad_text_not_synced`). - `list_ad_entities` gives each ad its `responsive_search_ad` text, `editable` and `has_pending_text_change`. ### After the edit - Each ad keeps its status, ID and history, and the ad platform reviews its new text again. - An ad changed in the ad platform since Roasby last read it is not sent. - Reverting writes the old text back. ## Keywords `preview_update_keywords` checks changes of Google Ads and Microsoft Ads keywords: `keywords`, each with its `keyword_id` and only what changes (`text`, `match_type`, `final_url`; null or empty takes the keyword's own final URL away). `update_keywords` makes them as one batch. See [Editing campaigns](/docs/editing-campaigns). ### In place or replace - A final URL, and a match type on Microsoft Ads, change in place. - A new text, and a new match type on Google Ads, are a replace: - The new keyword is added paused, with the old one's own bid and final URL. - The old one is paused, never removed. - So the keyword shows no ads until the new one is enabled. - `update_keywords`'s `keyword_next_step` says how to enable the new keywords once it is applied. `list_ad_changes` gives each as `replacement_id`, for `preview_enable_entities`. - Reverting a replace pauses the new keyword and gives the old one its status back. ### What each item says - `keyword_change`: `mode` (`in_place`, `replace` or `restore`), `replace`, and the keyword `before` and `after`. - `keyword_exists`: names the keyword the ad group already has, in `detail`. - `keyword_not_synced`: Roasby hasn't read the keyword's final URL yet. - `list_ad_entities` gives each keyword its own `final_url`, `editable` and `has_pending_keyword_change`. ## The change log and reverts `list_ad_changes` lists the change log of the workspace, newest first. See [Change log](/docs/change-log). - Every change made to its ads through Roasby (pauses and enables, daily budgets, bids and bidding, campaign settings, conversion goals, ad text, keywords, negative keywords, assets, and new campaigns, ad groups, ads and keywords), by a person, an AI assistant or the system, with the values before and after (budgets and bids in micros of the account currency). - Whether it is pending, applied (`partly_applied` when the platform refused part of it, with those parts in the reason) or failed (with the reason), and whether it was reverted. - A batch of changes confirmed together is one entry; `batch_id` lists that batch's items instead. `ad_account_id` narrows it to one ad account, `campaign_id` to one campaign (with everything in it and the change that created it), and `from` and `to` to those days (UTC). - `preview_revert_ad_change` and `revert_ad_change` revert one applied change. `preview_revert_ad_change_batch` and `revert_ad_change_batch` revert a batch, as a new batch. - A revert is itself a logged change, held to the same guardrails, and pending until the ad platform applies it. ## Support and docs - `preview_create_support_request` prepares a message to the Roasby support team (help with Roasby, billing, privacy or data requests, or an abuse report) without sending anything. - `create_support_request` sends it and returns a reference to quote in follow-ups. The team replies by email to your account address within 2 business days. It is limited to a few messages per hour, shared with the contact form. - `search_docs` searches the Roasby documentation and returns the best matching pages with a short summary and their slugs. - `get_doc` returns one documentation page as Markdown, by its slug. ## Read tools These tools only read: they never change your ad accounts. ### `get_current_workspace` **Get current workspace.** Returns the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its Roasby ID, name, URL slug, whether it is their personal workspace or a demo workspace (sample data, nothing is written to an ad platform), their role in it, whether they may change its ads (pause, enable, budgets, bids, reverts): owners and admins can, members only when the workspace allows it, and the max budget and bid change per step that newly connected ad accounts start with. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_workspaces` **List workspaces.** Lists the Roasby workspaces the connected user belongs to, by name: each one's Roasby ID (the workspace_id other tools take), name, the user's role, whether it is the user's current workspace on the web (the one tools act in without a workspace_id), whether it is their personal workspace or a demo workspace (sample data, nothing is written to an ad platform), whether the user may change its ads, and how many ad accounts it has (connected, or waiting to be reconnected). has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_workspace_members` **Get workspace members.** Lists the people in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (name, email and role) and the invitations that are still pending, one page at a time. has_more_members or has_more_invitations is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_accounts` **List ad accounts.** Lists the ad accounts (Google Ads, Microsoft Ads, ChatGPT Ads) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): platform, name, platform account ID, currency, time zone, status, whether it is still connected, its guardrails (max daily budget, max bid, max target CPA, min target ROAS and the max rise per step for budgets and bids, set by people in Roasby; each holds only once set, and changes outside them are refused), and when Roasby last synced it (data comes from the copy in Roasby, refreshed on a schedule or on request, not live from the platform; null means not synced yet). Accounts of a disconnected login are read-only history (needs_reconnect: the access ended, because the platform ended it or the person who connected it left, and a person reconnects it in Roasby), and so are suspended accounts (beyond the limit of active ad accounts of the workspace); people connect and disconnect platforms on the Ad accounts page in Roasby. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_entities` **List campaigns, ad groups, ads or keywords.** Lists one level of the ads in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): campaigns, ad groups, ads or keywords (entity_type), with their Roasby IDs, status, daily budget (campaigns, in micros of the account currency), keyword match type, and whether a status or budget change to them is still being applied. period (7d, 30d or 90d) adds the spend, clicks, conversions, conversion value and ROAS of each item over that many complete days (the same numbers as the Campaigns page), and for campaigns and ad groups the search impression share with the share lost to ad rank and to budget. Each keyword also has its insight from the ad platform: the Quality Score (1 to 10) with its expected click-through rate, ad relevance and landing page experience, the first page, top of page and first position bid estimates (micros and formatted), whether it is below the first page bid, and its approval, serving and primary status with the reasons; a missing score or estimate comes with the reason (not enough data, or not offered under automated bidding). Each responsive search ad has its text (headlines and descriptions with their pins, display paths, final URL) and whether Roasby can edit it; each keyword its own final URL and whether Roasby can change it. Each ad has its approval status (approved, under review, disapproved... or unknown when the platform reports none). An ad or keyword the ad platform disapproved, limited or is still reviewing has a policy object: each policy finding with the policy in plain words, how it limits serving, the headline or description it is about, the evidence the platform names, the countries where it cannot show, what can be changed, and whether the decision can be appealed (Microsoft Ads). Narrow it with ad_account_id, parent_id (the campaign of ad groups, the ad group of ads and keywords), campaign_id (the campaign of ad groups, ads or keywords), status, a name search, for keywords max_quality_score or below_first_page_bid, and for ads and keywords policy_issues_only. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_ad_changes` **List ad changes.** Lists the change log of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), newest first: every pause, enable, daily budget change, bid change, negative keyword change and new campaign made to its ads through Roasby, by a person, an AI assistant or the system, with the values before and after (budgets and bids in micros of the account currency), whether it is pending, applied (partly_applied when the platform refused part of it) or failed (with the reason), and whether it was reverted. A batch of changes confirmed together is one entry (batch, with its counts and status); batch_id lists that batch's items instead, and status narrows them to one status. ad_account_id narrows it to one ad account. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_performance_summary` **Get performance summary.** Summarizes the cross-platform ad performance (Google Ads, Microsoft Ads, ChatGPT Ads) of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) over the last 7, 30 or 90 complete days (ending yesterday, in each ad account's own days): spend, conversion value, ROAS, conversions, clicks and impressions, with the totals of the period before for comparison, every day of the period, and the split by platform and by ad account, largest spend first. Narrow it with ad_account_id or campaign_id. Amounts are in micros (1/1,000,000) and grouped per currency, never converted. Data comes from the copy in Roasby, refreshed on a schedule or on request, and includes disconnected and suspended accounts' history. The same numbers appear on the dashboard in Roasby. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_campaign_performance` **Get campaign performance.** Lists the campaigns of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) with their performance over the last 7, 30 or 90 complete days (ending yesterday): spend, conversion value, ROAS, conversions, clicks and impressions, plus status, type and daily budget, and for search campaigns the search impression share with the share lost to ad rank and to budget and the top and absolute top impression shares (a value the platform only reports as below 10% or above 90% is given as that bound), and its conversion goal setup (the account's goals or its own, what bidding aims for and problems such as a goal without an enabled conversion action), sorted by spend (or another metric), largest first. Narrow it with ad_account_id or campaign_id. Amounts are in micros (1/1,000,000) of each campaign's account currency, never converted. Data comes from the copy in Roasby, refreshed on a schedule or on request. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_search_terms` **Get search terms.** Lists what people searched before the ads of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) showed, over the last 7, 30 or 90 complete days (ending yesterday), per ad group: the matched keyword, spend, conversions, conversion value, clicks and impressions, sorted by spend (or another metric), largest first, and whether the term is already excluded, by a Roasby change or in the ad platform (added_as_negative). Narrow it with ad_account_id, campaign_id, ad_group_id or a text search. Amounts are in micros of each account's currency. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `find_wasted_spend` **Find wasted spend.** Finds money spent without results in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) over the last 7, 30 or 90 complete days (ending yesterday): the costliest search terms (per ad group) and keywords that brought no conversion, at or above min_cost_micros, and per currency the total spent on search terms without conversions. Search terms already excluded, by a Roasby change or in the ad platform, are left out. Narrow it with ad_account_id or campaign_id. Amounts are in micros of each account's currency. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_recommendations` **List recommendations.** Lists the changes Roasby recommends in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), the same list as its Recommendations page: search terms to exclude as negative keywords (they cost money without a conversion in the last 30 days and Roasby's AI judged them unrelated to the advertiser), keywords to pause (many clicks, no conversion) and daily budgets to raise (search campaigns that lose search impressions to their budget while converting at or below their ad account's cost per conversion), costliest first, each with its cost in micros of the account currency, its clicks and a short explanation. A budget raise has the suggested daily budget, within the ad account's guardrails (max daily budget, max change per step), never above them; when they leave no raise, blocked_by names the guardrail and user_actions the step for a person. Each open one that can be approved carries approve_with and approve_arguments: the preview and the arguments that approve it. status closed returns approved, resolved and dismissed ones; has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_alerts` **List anomaly alerts.** Lists the anomaly alerts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), the same list as its Alerts page: campaigns whose spend spiked on the last complete day or whose cost per conversion jumped over the last 7 days (or that kept spending without any conversion), and enabled ads the ad platform disapproved, each with the policy findings (the policy in plain words, the evidence, the countries, what can be changed and whether it can be appealed). Open alerts come most severe first (severity 1–5), each with its numbers in micros of the account currency and a short summary; an alert resolves on its own when the numbers settle or the ad is fixed. status resolved returns past alerts; has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_conversion_actions` **List conversion actions.** Lists how the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) track conversions: each conversion action (Google Ads) or conversion goal (Microsoft Ads) with where its conversions come from (website tag, Google Analytics 4 import, app, phone calls, upload, store), its status, category and goal, whether it is primary (counted toward bidding and the Conversions column), how it counts and gives credit, whether it is managed outside the account, and whether it is recording, with the last conversion Google Ads received (for Google Analytics 4 imports, only its day). Each account comes with what bidding aims for and the problems found (no primary conversion action in the goals bidding uses, a primary action that stopped recording). Narrow it with ad_account_id or primary_only; removed actions are left out unless include_removed is true. Data comes from the copy in Roasby, read every few hours, when an ad account is synced on request, and after a new search campaign. ChatGPT Ads conversion tracking is not read. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `list_assets` **List sitelinks, callouts and other assets.** Lists the text assets linked in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): sitelinks, callouts, structured snippets, prices and promotions, each with the Roasby ID of its link (for pausing and enabling it), where it is linked (the whole ad account, a campaign or an ad group), its status and its content, and whether a pause or enable of it is still being applied. Narrow it with ad_account_id, campaign_id (the campaign and its ad groups), ad_group_id, type or status; removed links are left out unless include_removed is true. Data comes from the copy in Roasby, read at every sync. ChatGPT Ads has no such assets. has_more is true when another page exists. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_keyword_ideas` **Get keyword ideas.** Gets keyword ideas for an ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) from its ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), from 1 to 20 seed keywords and/or a web page, in 1 to 10 countries and one language. Each keyword comes with its average monthly searches and monthly trend over the last 12 months, its competition (low, medium or high; Google Ads adds an index from 0 to 100) and a bid estimate in the account currency (Google Ads: the low and high top-of-page bid; Microsoft Ads: a suggested bid), the most searched first. A value is null when the platform has no number for it. The numbers are estimates and may be rounded. It reads the ad platform live, so a new request can take a few seconds and then answers with status running; the same request within a day is answered from Roasby's cache. ChatGPT Ads has no keyword research. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | Yes | ### `get_keyword_volumes` **Get keyword search volumes.** Gets the search volume and bid estimates of exactly the keywords given (up to 1,000) for an ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) from its ad platform's keyword planner (Google Ads Keyword Planner or Microsoft Ads Ad Insight), in 1 to 10 countries and one language: the average monthly searches and monthly trend over the last 12 months, the competition (low, medium or high; Google Ads adds an index from 0 to 100) and a bid estimate in the account currency (Google Ads: the low and high top-of-page bid; Microsoft Ads: a suggested bid), the most searched first. A value is null when the platform has no number for it, Google Ads combines close variants into one result, and keywords that came back without a result are listed in missing_keywords. The numbers are estimates and may be rounded. It reads the ad platform live, so a new request can take a few seconds and then answers with status running; the same request within a day is answered from Roasby's cache. ChatGPT Ads has no keyword research. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | Yes | ### `get_weekly_report` **Get weekly report.** Returns the latest weekly report of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (or the one with report_id), the same report its members get by email on Mondays and see on the Reports page: the last 7 complete days against the week before per currency (amounts in micros, never converted), the split by ad platform, the campaigns whose conversions rose or fell most, the search campaigns that lost a meaningful share of their impressions to budget or ad rank, the open alert and recommendation counts and the ad accounts to reconnect, with the short summary Roasby's AI wrote (summary_by_ai is false when there is none). Reports keep the numbers they were sent with. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `search_docs` **Search Roasby docs.** Searches the Roasby documentation (setup, connecting AI assistants, the safety model, tool reference) and returns the best matching pages with a short summary and their slugs. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `get_doc` **Read a Roasby docs page.** Returns one Roasby documentation page as Markdown, by its slug (for example "connect-your-ai" or "safety-model"). | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ## Preview tools Each preview checks a change without making it and returns a one-time confirmation token for its change tool. ### `preview_activate_ad_account` **Preview making an ad account active.** Shows whether a suspended ad account (read-only because the workspace has more ad accounts than its limit) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) can be made active again, without changing anything. When the workspace is at its limit, replace_ad_account_id names the active account that becomes read-only in its place. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. Owners and admins only. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_archive_recommendation` **Preview dismissing a recommendation.** Shows whether an open recommendation in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) can be dismissed, without changing anything. Dismissing changes nothing in the ad account; Roasby just never suggests it again. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_pause_entity` **Preview pausing an ad item.** Shows what pausing a campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_enable_entity` **Preview enabling an ad item.** Shows what enabling (resuming) a paused campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow it, without changing anything. Enabling can start spending money, so a campaign above the ad account's max daily budget, or only partly created, is refused. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_pause_entities` **Preview pausing ad items together.** Shows what pausing many campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules allow each one, without changing anything: the items that may change, the refused ones with why, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_enable_entities` **Preview enabling ad items together.** Shows what enabling (resuming) many paused campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules allow each one, without changing anything: the items that may change, the refused ones with why (such as a campaign above the ad account's max daily budget), and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_campaign_budget` **Preview a campaign budget change.** Shows what setting a campaign's daily budget in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (the budget before and after, in micros and formatted in the account currency) and whether the ad account's guardrails and Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_campaign_settings` **Preview a campaign settings change.** Shows what changing the settings of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do: any of its countries, location option, search partners, final URL suffix, tracking template, ad schedule, device bid adjustments, ad rotation and (Microsoft Ads) languages, each section before and after, and whether the guardrails and safety rules allow it, without changing anything. All sections are one change. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_conversion_goals` **Preview a conversion goals change.** Shows what changing the conversion goals a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) bids on would do: the ad account's goals, or goals chosen for the campaign, before and after, which chosen goals are not recording conversions, and whether the safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bidding` **Preview a bidding change.** Shows what changing the bidding strategy and targets of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (manual cost per click, maximize clicks, maximize conversions with an optional target CPA, maximize conversion value with an optional target ROAS, or target impression share), or a Google Ads ad group's own target CPA: before and after, whether its conversion goals record conversions, the guardrails, and whether the safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bid` **Preview a bid change.** Shows what setting the max cost per click of an ad group or keyword in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules and the ad account's guardrails allow it, without changing anything. Only items with bids_adjustable true can change: campaigns under automated bidding ignore these bids. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_bids` **Preview bid changes together.** Shows what setting the max cost per click of many ad groups and keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) together would do, and whether Roasby's safety rules and the ad account's guardrails allow each one, without changing anything: each new bid (an amount per item, one amount for all, a change in percent, or each keyword's first page bid estimate up to a cap), the refused items with why, the bids the guardrails limited, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_negative_keywords` **Preview adding negative keywords.** Shows what excluding keywords from a campaign or an ad group in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (every keyword with its match type) and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_keywords` **Preview adding keywords to an ad group.** Shows what adding keywords (text, match type, optional bid and final URL) to an ad group of a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the keywords that may be added, the refused ones with why (too long, duplicates, blocked by a negative keyword, above the max bid...), and the totals. Every keyword is created paused. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_ad_groups` **Preview adding ad groups to a campaign.** Shows what adding ad groups (each with a name, a default bid, and optionally keywords, negative keywords and a responsive search ad) to a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one with its parts, without changing anything: the ad groups that may be added, the refused ones with why and the part that breaks the rule (a name the campaign has, a keyword that is too long, a bid above the max bid...), the totals and the platform operations. Every ad group is created paused, with its keywords and ad under it. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_responsive_search_ads` **Preview adding responsive search ads to ad groups.** Shows what adding responsive search ads (headlines and descriptions, each optionally pinned to a position, a final URL, display paths and a final URL suffix) to ad groups of search campaigns in one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the ads that may be added, the refused ones with why and the part that breaks the rule (a headline that is too long, two headlines that are the same, pins that leave a position empty...), the totals and the platform operations. Every ad is created paused. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_add_assets` **Preview adding sitelinks, callouts and other assets.** Shows what adding text assets (sitelinks, callouts, structured snippets, prices and promotions) to an ad account, a search campaign or one of its ad groups (or several campaigns or ad groups of one ad account, every asset to each) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each one, without changing anything: the assets that may be added, the refused ones with why (too long, too few values or rows, an asset that is there already, a Microsoft Ads campaign or ad group that is not paused...), and the totals. On Google Ads each asset is linked paused; Microsoft Ads has no paused links, so there Roasby links only to paused campaigns and ad groups. When some may be added, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_ads` **Preview ad text edits.** Shows what editing the text of responsive search ads of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each edit, without changing anything: the given headlines, descriptions (with their pins), display paths or final URL of each ad, or a literal find and replace across the ads of an ad account, campaign or ad group. It lists each ad's whole text after and each part that changes before and after, the ads refused with why and the text they would have had, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_update_keywords` **Preview keyword changes.** Shows what changing the text, match type or own final URL of keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do, and whether Roasby's safety rules allow each change, without changing anything. A final URL, and a match type on Microsoft Ads, change in place; a new text, and a new match type on Google Ads, replace the keyword: the new keyword is added paused to the same ad group with the old one's own bid and final URL, and the old one is paused, never removed. It lists each keyword before and after, whether it is a replace, the keywords refused with why, and the totals. When some may change, it returns one confirmation_token for all of them, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_search_campaign` **Preview a new search campaign.** Shows the complete search campaign that would be created in one of the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (budget, bidding, countries, the advertiser's EU political ads declaration, its negative keywords and its ad groups with their keywords, negative keywords and responsive search ads) and whether Roasby's safety rules allow it, without changing anything. The campaign is created paused and its daily budget must stay within the account's max daily budget. If any part breaks a rule, the preview names every part that does. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_chat_campaign` **Preview a new ChatGPT Ads campaign.** Shows the complete ChatGPT Ads campaign that would be created in one of the ChatGPT Ads accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (budget, bidding, countries, context hints and the chat card ad with its image) and whether Roasby's safety rules allow it, without changing anything. The campaign is created paused and its daily budget must stay within the account's max daily budget. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_revert_ad_change` **Preview reverting an ad change.** Shows what reverting an applied ad change in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do and whether Roasby's safety rules allow it, without changing anything. When it is allowed, it returns a confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_revert_ad_change_batch` **Preview reverting a batch of ad changes.** Shows what reverting a batch of ad changes in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) would do (each item it applied gets its value before back) and whether Roasby's safety rules allow each item, without changing anything. When some may change, it returns one confirmation_token, valid for 10 minutes, once. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ### `preview_create_support_request` **Preview a message to Roasby support.** Prepares a message from the connected user, about the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), to the Roasby support team (help with Roasby, billing, privacy or data requests, or an abuse report) without sending anything. It returns a confirmation_token, valid for 10 minutes, once. The team replies by email to the user's account address. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | Yes | No | No | ## Change tools These tools change something. A change tool with a preview makes only the change its preview checked, after you confirm it. ### `run_ad_account_sync` **Sync an ad account now.** Asks Roasby to refresh its copy of the data of one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (campaigns, ad groups, ads, keywords, metrics, search terms) from the ad platform now, instead of waiting for the scheduled sync. It only reads from the platform and never changes ads. The sync runs in the background and usually takes a few minutes; last_synced_at on the ad account changes when it finishes, and last_sync_error is set when it fails. It also reads the conversion goals again. Changes made through Roasby are in its copy without it: applied values at once, and new campaigns, ad groups, keywords, ads and assets with a sync Roasby runs by itself a few minutes later (follow_up_sync_due_at on the ad account). Each account can be synced this way only so often; the answer says when it is allowed again. started is false when the account was synced too recently, or when a sync is already on its way (next_sync_allowed_at is then about when its new data shows). | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | Yes | ### `activate_ad_account` **Make an ad account active.** Makes a suspended ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) active again (synced and changeable); with replace_ad_account_id, that active account becomes read-only in its place. Requires the confirmation_token from a preview of the same change. Nothing is disconnected or deleted, and the swap can be made again the other way. Owners and admins only. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `archive_recommendation` **Dismiss a recommendation.** Dismisses an open recommendation in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so Roasby never suggests it again. Nothing changes in the ad account. Requires the confirmation_token from a preview of the same change. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `pause_entity` **Pause an ad item.** Pauses a campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `enable_entity` **Enable an ad item.** Enables (resumes) a paused campaign, ad group, ad, keyword or asset link in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so it can start spending money. Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `pause_entities` **Pause ad items together.** Pauses many campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change. Each item is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `enable_entities` **Enable ad items together.** Enables (resumes) many paused campaigns, ad groups, ads, keywords and asset links (sitelinks, callouts and other assets) of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, so they can start spending money. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change. Each item is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_campaign_budget` **Update a campaign budget.** Sets the daily budget of a campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The budget must stay within the ad account's guardrails. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_campaign_settings` **Update campaign settings.** Changes the settings of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (countries, location option, search partners, final URL suffix, tracking template, ad schedule, device bid adjustments, ad rotation, languages) as one change. Requires the confirmation_token from a preview of the same change. Bid adjustments must stay within the ad account's max bid change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_conversion_goals` **Update conversion goals.** Changes the conversion goals a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) bids on: the ad account's goals, or goals chosen for the campaign. Requires the confirmation_token from a preview of the same change. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bidding` **Update bidding.** Changes the bidding strategy and targets of a Google Ads or Microsoft Ads search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), or a Google Ads ad group's own target CPA. Requires the confirmation_token from a preview of the same change. Targets stay within the guardrails set on the ad account (max bid for a max cost per click, max target CPA, min target ROAS, and the max bid change for a rise). The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bid` **Update a bid.** Sets the max cost per click of an ad group or keyword in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names). Requires the confirmation_token from a preview of the same change. The bid must stay within the ad account's guardrails. The change is logged and can be reverted; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_bids` **Update bids together.** Sets the max cost per click of many ad groups and keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the items that preview allowed change, each within the ad account's guardrails. Each bid is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `add_negative_keywords` **Add negative keywords.** Excludes keywords from a campaign or an ad group in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), so its ads stop showing for those searches. Requires the confirmation_token from a preview of the same change. Negative keywords the target already has are left as they are. The change is logged and can be reverted (reverting takes away exactly the negative keywords it added); it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_keywords` **Add keywords to an ad group.** Adds keywords to an ad group of a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused. Requires the confirmation_token from a preview of the same keywords; only the keywords that preview allowed are added. Each keyword is logged and can be reverted (paused), alone or with its batch; keywords are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_ad_groups` **Add ad groups to a campaign.** Adds ad groups to a search campaign in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused with its keywords, negative keywords and responsive search ad under it. Requires the confirmation_token from a preview of the same ad groups; only the ad groups that preview allowed are added. Each ad group is logged and can be reverted (paused), alone or with its batch; ad groups are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_responsive_search_ads` **Add responsive search ads to ad groups.** Adds responsive search ads to ad groups of search campaigns in one ad account of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch, each created paused. Requires the confirmation_token from a preview of the same ads; only the ads that preview allowed are added. Each ad is logged and can be reverted (paused), alone or with its batch; ads are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `add_assets` **Add sitelinks, callouts and other assets.** Adds text assets (sitelinks, callouts, structured snippets, prices and promotions) to an ad account, a search campaign or one of its ad groups (or several campaigns or ad groups of one ad account, every asset to each) in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch: on Google Ads each linked paused, on Microsoft Ads linked to a paused campaign or ad group. Requires the confirmation_token from a preview of the same assets; only the assets that preview allowed are added. Each asset is logged and can be reverted (its link paused, or on Microsoft Ads taken away; the asset itself stays), alone or with its batch; assets are pending until the ad platform adds them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `update_ads` **Update ad text.** Edits the text of responsive search ads of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) in place, as one batch: headlines, descriptions with their pins, display paths and final URLs, given per ad or by a literal find and replace. Requires the confirmation_token from a preview of the same batch; only the ads that preview allowed change. Each ad keeps its status, ID and history, and the ad platform reviews the new text again. Each edit is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `update_keywords` **Update keywords.** Changes the text, match type or own final URL of keywords of one ad account in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) as one batch. Requires the confirmation_token from a preview of the same batch; only the keywords that preview allowed change. A final URL, and a match type on Microsoft Ads, change in place, keeping the keyword's status, ID and history; a new text, and a new match type on Google Ads, replace the keyword: the new keyword is added paused and the old one is paused, never removed, so it shows no ads until the new one is enabled. Each change is logged and can be reverted, alone or with its batch; items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `create_search_campaign` **Create a search campaign.** Creates a complete search campaign, paused, in one of the ad accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its budget, bidding, countries, negative keywords and every ad group with its keywords, negative keywords and responsive search ads, as one change. Requires the confirmation_token from a preview of the same change. Nothing runs until the user enables the campaign. The change is logged; reverting it pauses the campaign. It is pending until the ad platform creates it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `create_chat_campaign` **Create a ChatGPT Ads campaign.** Creates a complete ChatGPT Ads campaign, paused, in one of the ChatGPT Ads accounts of the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): its budget, bidding, countries, one ad group with context hints and one chat card ad whose image ChatGPT Ads fetches from image_url. Requires the confirmation_token from a preview of the same change. Nothing runs until the user enables the campaign; ChatGPT Ads reviews the ad once it is created. The change is logged; reverting it pauses the campaign. It is pending until the ad platform creates it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ### `revert_ad_change` **Revert an ad change.** Reverts an applied ad change in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names) (restores the value before it). Requires the confirmation_token from a preview of the same change. The revert is itself a logged change, held to the same guardrails and limits; it is pending until the ad platform applies it. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `revert_ad_change_batch` **Revert a batch of ad changes.** Reverts a batch of ad changes in the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names): each item the batch applied gets its value before back, as a new batch. Requires the confirmation_token from a preview of the same revert. The revert is itself logged, held to the same guardrails; its items are pending until the ad platform applies them. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | Yes | No | ### `create_support_request` **Send a message to Roasby support.** Sends a message from the connected user, about the Roasby workspace the tool acts in (the user's current workspace, or the one workspace_id names), to the Roasby support team. Requires the confirmation_token from a preview of the same message. Returns a reference to quote in follow-ups; the team replies by email within 2 business days. Limited to a few messages per hour, shared with the contact form. | Read-only | Destructive | Reaches the open web | | --- | --- | --- | | No | No | No | ## Limitations - There are no delete tools, and no tools to connect ad platforms, set guardrails or safety defaults, manage billing or change account settings: people do those in Roasby on the web. - When only a person can do something, a tool result lists it in `user_actions` (what, why, where and a link when there is one). - Your assistant is told to explain each step and never claim it did it. - Steps marked `optional` are choices, such as raising a guardrail instead of making a smaller change. - The confirmation token proves a preview ran, not that you agreed. - A batch changes one ad account at a time, with only so many items in one batch. - Bulk bid changes: - They keep the max bid change per step, so a larger rise takes several batches (a cut takes one). - First page bid estimates exist only for keywords, never under automated bidding. - Conversion tracking: - It is as of Roasby's last read (every few hours). ChatGPT Ads conversion tracking is not read. - Conversion actions are never changed. `preview_update_conversion_goals` changes only which goals a Google Ads or Microsoft Ads search campaign bids on, and never creates a custom goal. - Keyword research (`get_keyword_ideas`, `get_keyword_volumes`): - It asks the ad platform live: a new search can take a few seconds. - Its numbers are estimates kept for a day. - A workspace runs only so many new searches an hour. - ChatGPT Ads has none. - Impression share: - It covers search campaigns and their ad groups only, as of the last sync. - Google Ads reports below 10% and lost above 90% only as bounds. - On Google Ads, ad groups have no `lost_to_budget`: Google reports the share lost to budget for campaigns only. - Keyword insight: - It is as of the last sync. - Microsoft Ads reports it only for keywords with recent activity and has no below first page bid status. - Adding keywords works on Google Ads and Microsoft Ads search campaigns only, one add at a time per ad group, and every keyword is added paused. - Adding ad groups: - It works on Google Ads and Microsoft Ads search campaigns only, one add at a time per campaign. - Every ad group is added paused. - Each ad group, keyword, negative keyword and ad counts toward the items of one batch. - Ad text edits: - They work on Google Ads and Microsoft Ads responsive search ads only, once synced, one edit at a time per ad. - A find and replace looks at up to 10,000 ads. - Keyword changes: - They work on Google Ads and Microsoft Ads search campaigns only, once a sync read the keyword's own final URL. - One change at a time per keyword: a pending replace or its revert holds both keywords, and a keyword named twice in one call is refused the second time. - Reverting a replace whose new keyword was removed already only gives the old keyword its status back. - A new text, and a new match type on Google Ads, replace the keyword (the new one added paused, the old one paused, never removed). - Bidding changes (`preview_update_bidding`): - They work on a Google Ads or Microsoft Ads search campaign's own strategy, once synced. - Only when Roasby could set the bidding before back exactly (`bidding_not_revertible`). - Ad group target CPAs on Google Ads only, under a campaign target CPA. - A max cost per click stays within the max bid, a target CPA within the max target CPA, a target ROAS at or above the min target ROAS, each once set, and each moves at most the max bid change per step. - Maximize conversions and conversion value aim at nothing until the goals record conversions: the preview warns. - On Microsoft Ads, Roasby doesn't change target impression share yet, and never adds a target CPA or ROAS to, or takes one from, a campaign that keeps its strategy. - Campaign settings: - They work on Google Ads and Microsoft Ads search campaigns only, once synced. - A bid adjustment rises at most one max bid change per step. - Regions, cities, a radius, excluded places and the Google Display Network are changed in the ad platform. See every limit by platform on [Limitations](/docs/limitations). --- # Limitations > What Roasby and each ad platform can't do today, why, and what you can do instead, in one place. Roasby can't do everything an ad platform's own website can. Some limits come from the ad platforms, some are choices Roasby made to keep your ads safe, and some are features Roasby doesn't have yet. Each row says what you can do instead. The feature pages repeat the limits that apply to them in their own **Limitations** section. When something can only be done by a person, your AI assistant tells you what to do, why and where (with a link when there is one), for example setting a guardrail in Roasby or a setting in Google Ads. It never does those steps for you and never says it did. ## Limitations by platform | Limitation | Google Ads | Microsoft Ads | ChatGPT Ads | What you can do instead | | --- | --- | --- | --- | --- | | Campaign types Roasby creates | Search campaigns | Search campaigns | Chat campaigns | Create other types (App, Performance Max, Display, Shopping, Video) in the ad platform; Roasby reads them and can pause or enable them. | | Keywords and search terms | Yes | Yes | None: ChatGPT Ads has no keywords | On ChatGPT Ads, describe where your ads fit with context hints when you create a campaign. | | Negative keywords | Exact, phrase and broad match | No broad match negative keywords: exact and phrase only | None | Use phrase match on Microsoft Ads for the closest result. | | Adding keywords to an existing ad group | Search campaigns; at most 80 characters and 10 words, without the characters Google Ads refuses in keywords (such as `!`, `@`, `%`, `*`, `?`, brackets and the pipe) | Search campaigns; at most 100 characters | None: ChatGPT Ads has no keywords | Shorten the keyword or leave the character out. Each keyword is added paused; a keyword's own bid stays within the account's max bid when it has one; an ad group takes at most 20,000 keywords and negative keywords. | | Adding ad groups to an existing campaign | Search campaigns; names up to 254 characters; each ad group made whole or not at all | Search campaigns; names up to 255 characters; made step by step, so a failed later step leaves the ad group paused and partly made; Microsoft's own search network only | None: Roasby adds no ad groups to ChatGPT Ads | See note 1. | | Adding responsive search ads to an existing ad group | Search ad groups; no total of ads per ad group | Search ad groups; at most 100 ads (enabled and paused) per ad group | None: Roasby adds no responsive search ads to ChatGPT Ads | Each ad is added paused; enable it with your assistant. | | Enabled responsive search ads | At most 3 per ad group | At most 3 per ad group | — | Pause one of the others before you enable a fourth. | | Character widths in ads | Characters of Chinese, Japanese and Korean count as two (a headline holds 15) | The same, and emoji count as two | — | Shorten the text; the preview names the part that is too long. | | Pinning headlines and descriptions | Allowed (headlines 1 to 3, descriptions 1 to 2); at least as many unpinned ones as positions nothing is pinned to; pinning lowers ad strength | The same | — | Pin only text that must show, 2 or 3 to a position rather than one. | | Policy reviews and exceptions for a refused ad | Only in the Google Ads web interface; Roasby never asks for one | Appeals only in Microsoft Advertising | — | Change the ad's wording and add it again, or ask the ad platform for a review on its own website. | | Ad group start and end dates | Don't exist: only campaigns have dates | Not set by Roasby | — | Set dates on the campaign. | | Political ads | You declare EU political advertising for each new campaign | Political ads are not accepted | — | On Microsoft Ads, answer no when your assistant asks about political ads. | | Manual cost per click on a new search campaign | Yes | Becomes enhanced cost per click: Microsoft raises or lowers your max cost per click to win conversions | Max cost per click or maximize clicks | The preview says so before you confirm. | | Lifetime budgets and shared budgets | Not changed in Roasby | Not changed in Roasby | A campaign with a lifetime budget keeps it: its budget is not changed in Roasby | Change them in the ad platform itself. | | Impression share | Search campaigns and ad groups only; a share below 10% and a lost share above 90% are reported only as those bounds; ad groups have no share lost to budget (campaigns only) | Search campaigns and ad groups only; the share often comes about a day later than the other numbers | None: ChatGPT Ads reports no impression share | Roasby shows "<10%", ">90%" or "Not enough data" instead of a made-up number. | | Raise budget recommendations | Search campaigns with a daily budget of their own, within the guardrails | The same | None: ChatGPT Ads reports no impression share | Shared and lifetime budgets are never raised. After a budget change (in Roasby or in the ad platform), a new suggestion waits for 14 days at the new budget, and Roasby needs an impression share on at least 80% of the days. | | Quality Score and bid estimates | None for a keyword with too few searches; no bid estimates under automated bidding | The same, read only for keywords with activity recently (others keep what Roasby read before); no **Below first page bid** status | None: ChatGPT Ads has no keywords | Roasby says "Not enough data yet" or "Not offered under automated bidding" instead of a number. On Microsoft Ads, compare the max bid with the first page bid yourself. | | Policy review of ads and keywords | Findings for ads, each headline and description, and keywords, with evidence and countries; sitelinks, callouts and other assets have no findings in Roasby | Reasons only for disapproved and limited ads and keywords, with the countries and whether you can appeal | An ad's approval only (approved, under review or disapproved), without reasons | Reviews, exceptions and appeals are only in the ad platform's own website: Roasby shows the findings and what to change, and never requests them. | | Conversion tracking | Conversion actions, the account's goals and each campaign's goals (including custom goals), read every few hours and with Sync now; see note 2 | Conversion goals with their tag status, and the goals a campaign chose; no goals by category | Not read | See note 3. | | Keyword research | Ideas from seed keywords or a web page, and volumes of your own keywords, with a low and high top-of-page bid; volumes are rounded, more so for accounts with little spend; no Albanian, Bosnian, Macedonian or Maltese | The same with one suggested bid, in English, French and German only | None: ChatGPT Ads has no keyword research | Countries only. Each new search asks the platform live, so a workspace runs only so many new searches an hour; the same search within a day is answered at once. | | Max bids | Ad groups and keywords with manual cost per click | Ad groups and keywords with manual or enhanced cost per click | Ad groups with a max cost per click | Under automated bidding the platform sets bids; your assistant can change the bidding (see below). | | Bidding strategies | A search campaign's own strategy: manual cost per click, maximize clicks (a max cost per click it has is kept), maximize conversions (target CPA), maximize conversion value (target ROAS), target impression share; ad group target CPA under maximize conversions with a campaign target CPA | The same strategies (manual is enhanced cost per click), with the exceptions in note 4; no ad group target CPA | None: changed in ChatGPT Ads Manager | See note 5. | | Sitelinks, callouts, structured snippets and other text assets | Added to the whole account, a search campaign or an ad group, each linked paused; text is never edited and assets are never removed | Added only to a paused search campaign or ad group, never to a whole account, because Microsoft Ads can't pause an asset link (pausing one takes the link away); see note 6 | None: ChatGPT Ads has no such assets | See note 7. | | Changing many bids at once | Ad groups and keywords; each bid keeps the max bid change per step | The same | Ad groups only | A larger rise takes several steps (cuts take one): ask your assistant to limit the bids to the guardrails to take the largest allowed step each time, or raise the max bid change on the **Ad accounts** page. | | How a sync reads changes made in the ad platform | A scheduled sync reads again only what Google Ads' change history says changed since the last sync; see note 8 | Every sync reads the whole account: Microsoft Ads keeps its change history only in its bulk service | Every sync reads the whole account: ChatGPT Ads has no change history | Select **Sync now** to read the whole account at once. | | A campaign deleted in the ad platform | Shown as archived after the next sync: Google Ads reports it as removed | Shown as archived, with everything under it, after the next sync: Microsoft Ads no longer returns a deleted campaign | As ChatGPT Ads reports it | Select **Sync now** to see it at once. | | Raising keywords to their first page bid | Keywords with a first page bid estimate (none under automated bidding or with too few searches) | Keywords with an estimate, read only for keywords with recent activity | None: ChatGPT Ads has no keywords | Keywords without an estimate are left out with the reason; set their bids as an amount or a percent instead. Estimates are as of the last sync. | | Editing campaign settings | Search campaigns; countries, location option, search partners, tracking, ad schedule, device bid adjustments and ad rotation, sent all at once (every section or none); the Google Display Network is shown but never changed | The same plus languages; see note 9 | None: ChatGPT Ads campaigns have none of these settings | Change what Roasby can't (regions, cities, radius, excluded places, location bid adjustments, the Display Network) in the ad platform itself. | | Editing keywords | Text and match type can't change in place: Roasby replaces the keyword (the new one added paused, the old one paused); its own final URL changes in place | The match type and own final URL change in place; a new text replaces the keyword | None: ChatGPT Ads has no keywords | Enable the new keyword when you want it to run: it starts without the old one's history. If the ad group already has the new keyword, enable that one instead. | | Editing ad text | Responsive search ads only, once Roasby has read their text; headlines, descriptions with their pins, display paths and the final URL, in place (the ad keeps its status and history); the ad's own final URL suffix and a second final URL stay as they are | The same | None: ChatGPT Ads ads are chat cards, edited in ChatGPT Ads Manager | Edit other ad types and the text of assets in the ad platform itself. The ad platform reviews new text again, so the ad may show as under review for a while. | | Ad schedule | At most 6 time slots a day, in quarter hours, in the ad account's time zone; -90% to +900% per slot | At most 7 a day and 49 in all, in the campaign's time zone; -90% to +900% per slot | — | Merge time slots; slots of one day may not overlap. | | Device bid adjustments | Mobile, tablet and desktop: -100% (no ads) or -90% to +900% | -100% to +900% | — | A rise is limited to the max bid change per step, for each device in each scheduled hour (device × hour, from what it had before); ask your assistant to limit the bid adjustments to take the largest allowed step. | | Minimum daily budget | Google's own minimum | Microsoft's own minimum | $25 a day in USD accounts, refused below | Choose a budget at or above the minimum. | | Language targeting | Search campaigns have no language targeting: Google matches languages itself, so the languages you ask for are only noted | Microsoft's ad languages (default: all); some are not yet available in every account | — | On Google Ads, write your ads in the languages of the people you want to reach. | | Countries | Any number per new campaign, whole countries only | Any number per new campaign, whole countries only | Only the countries ChatGPT Ads serves, up to 25 | Add regions, cities or a radius in the ad platform itself. | | Campaigns without an EU political ads declaration | Google Ads refuses every campaign change in the account until each campaign declares it; the preview names the campaigns, and a refused change says why in the change log | — | — | Declare it for those campaigns (or the whole account) in the Google Ads web interface, then try again. | | Ad preview | Google's Ad Preview and Diagnosis is not in its API | — | — | Check how your ads look in Google Ads itself. | | EU political ads declaration for the whole account | Only in the Google Ads web interface | — | — | Roasby declares it for each campaign it creates, after asking you. | | Automatically created assets | Turning them off is only in the Google Ads web interface | — | — | Turn them off in the Google Ads web interface if you want only the ad text you approved. | | Start and end dates | On the campaign only, not per ad group | On the campaign | On the campaign | Set dates on the campaign when you create it. | ### Notes on the table 1. **Adding ad groups.** Each ad group is added paused with its keywords and ad; under manual bidding it needs a default bid, within the max bid once one is set; at most 20,000 ad groups per campaign. Finish a partly made Microsoft Ads ad group in Microsoft Ads, and turn on search partners there if you want them. 2. **Conversion tracking on Google Ads.** Recording is judged by the last conversion (when Google Ads received it, or the day for Google Analytics 4 imports; no tag status in its API). Google Analytics 4 key events show once imported. See [Conversions](/docs/conversions). 3. **What to do about conversion tracking.** Create and edit conversion actions in the ad platform, and Google Analytics 4 key events in Google Analytics. Your assistant can change which goals a search campaign bids on (Google Ads and Microsoft Ads; on Microsoft Ads only between goals of the campaign's own, never to or from the account's goals, which Microsoft offers no way to set back). Goals that record nothing under bidding toward conversions are warned about, not refused. Roasby never creates a custom goal. 4. **Bidding strategies on Microsoft Ads.** The same strategies as Google Ads, except target impression share, which Roasby doesn't change yet; a target CPA or target ROAS is never added to or taken from a campaign that keeps its strategy (Microsoft Ads offers no way to take one away, so it couldn't be reverted). A max cost per click on maximize clicks, conversions or conversion value stays while the strategy stays; once the strategy changes, Microsoft Ads doesn't take it again, so a revert sets the strategy back without it, and the preview says so first. 5. **What to do about bidding.** Portfolio strategies, enhanced cost per click on Google Ads, other strategies Roasby could not put back, and the Microsoft Ads changes it doesn't make are done in the ad platform. A max cost per click stays within the max bid and a target CPA within the max target CPA, a target ROAS at or above the min target ROAS when set, and each moves at most the max bid change per step, measured from the most recent target Roasby set or took away when the campaign has none now. Your assistant's reverts keep these guardrails; you can revert on the **Change log** page, which restores the exact earlier target. See [Bidding and goals](/docs/bidding-and-goals). 6. **Microsoft Ads asset limits.** At most 20 of a type per place; callouts show only from 2 to 20 per place; amounts in some currencies only, promotions in some languages only. 7. **What to do about assets.** Pause the campaign or ad group before you add assets on Microsoft Ads, and enable it when you want them to show. Change an asset's text, or add images, logos and business names, in the ad platform itself. See [Assets](/docs/assets). 8. **How a Google Ads sync reads changes.** A scheduled sync reads again only what Google Ads' change history says changed since the last sync (campaigns, budgets, settings, ad groups and assets; ads and keywords every time), and the whole account at least once a day, on **Sync now** and after Roasby's own new campaigns. A change made in the last few minutes before a sync shows with the next one; a change to a shared (portfolio) bid strategy, which the change history doesn't list, shows with the next full read. 9. **Editing campaign settings on Microsoft Ads.** Search partners and ad rotation are per ad group, so they are set on every ad group the campaign has; sections are sent one after another, so a refused one leaves the ones before it applied. ## What Roasby chose not to do These keep your ads safe and stay this way: - **No deleting.** Roasby never deletes or removes campaigns, ad groups, ads or keywords, because a removed item can't come back on most ad platforms. Pause them instead, in Roasby or through your assistant. The only things it takes away are targeting settings it replaces when you edit a campaign's countries or ad schedule (the change log keeps them, and reverting puts them back) and negative keywords a Roasby change added, when you revert it. - **Only people set guardrails.** Max daily budgets, max bids, max target CPAs, min target ROAS, the max rise per step, the workspace's safety defaults and **Allow members to change ads** are set in Roasby on the web. Your AI assistant reads them but can never loosen them. - **Creating, editing and research are done through your AI assistant only.** Creating campaigns, adding ad groups, ads and keywords, changing bids, campaign settings, ad text and keywords, and keyword research have no web pages. On the web you watch your ads, pause and enable them, set daily budgets, exclude searches as negative keywords on the **Search terms** page, approve recommendations and revert changes; your assistant can do all of those too. - **New keywords, ad groups and ads start paused**, even in a running ad group or campaign, and reverting them pauses them: Roasby never removes a keyword, an ad group or an ad. Changing a keyword's text (or its match type on Google Ads) adds the new keyword paused and pauses the old one, so the keyword shows no ads until you enable the new one. A keyword that a negative keyword of its ad group or campaign blocks (by the negative's match type) is refused, because it would never show ads; the refusal names that negative. - **No automatic rules** such as "pause a campaign when its cost per conversion goes above X". [Alerts](/docs/alerts) and [recommendations](/docs/recommendations) tell you what changed, and you or your assistant act after you confirm. - **No file import.** Give your AI assistant the file you have (a Google Ads Editor export or a spreadsheet): it reads it and fills in the campaign itself, and you confirm the preview. - **A batch is one ad account.** Pausing or enabling many items together works within one ad account at a time, and a workspace can change only so many items in one batch. Split larger changes into several batches; each has its own preview and confirmation. - **Some things stay on the web**: connecting and disconnecting ad platforms, billing, your account settings and your AI connections. ## What Roasby can't do yet - **Very large new campaigns in one step.** A new search campaign holds up to 1,000 ad groups (each with up to 1,000 keywords, 100 negative keywords and 3 ads) and 10,000 negative keywords of its own, within 10,000 operations in all, and it targets whole countries. Your assistant creates a larger one in parts: the campaign with part of its ad groups, then the rest added to it. A ChatGPT Ads campaign has one ad group and one chat card. - **Adding to existing campaigns.** Roasby can add ad groups (each with up to 3 ads) to a search campaign, and keywords and responsive search ads to an ad group, that already exist (through your assistant). It can add negative keywords to an existing campaign or ad group, up to 100 in one change. - **Editing settings and ads.** Roasby can edit a search campaign's countries, location option, search partners, tracking, ad schedule, device bid adjustments, ad rotation and (Microsoft Ads) languages, the text of responsive search ads, and keywords (text, match type and own final URL; a new text, and a new match type on Google Ads, replace the keyword), and bidding (see [Bidding and conversion goals](/docs/bidding-and-goals)), but not a campaign's dates, regions, cities or a radius, or ads of other types. Change those in the ad platform itself. - **Image and brand assets.** Images, logos and business names are added in the ad platform itself, and so is any change to an asset's text: Roasby adds sitelinks, callouts, structured snippets and the other text assets, and pauses or enables their links. - **Shared negative keyword lists** are not read or changed. Roasby reads the negative keywords set directly on campaigns and ad groups. ## How the data works - **A synced copy.** Roasby reads your ad accounts on a schedule and answers from its own copy, so reports and your assistant are fast. Numbers are as fresh as the account's last sync. - **Roasby's own changes show at once.** Its status, budget and bid changes show as soon as they apply. After a new campaign Roasby usually syncs the account within a few minutes (at most once every 5 minutes and 24 times a day per account, and not while Roasby's shared Google Ads capacity is busy). - **Changes made in the ad platform itself**, and fresh numbers, come with the next scheduled sync (one made in Google Ads in the last few minutes before it, with the sync after), or right away with **Sync now** (every 5 minutes on Microsoft Ads and ChatGPT Ads) on the [Ad accounts](/docs/ad-accounts) page. - **Late conversions.** Platforms keep adding late conversions, so each sync also refreshes the last few days. - **Currencies are never converted.** Totals are shown per currency. - **ChatGPT Ads conversion value** needs purchase tracking in ChatGPT Ads. Until then, value and ROAS show as n/a, and its spend is left out of the combined ROAS. - Items removed in the ad platform stay in Roasby, read-only, with their history. ## Workspaces - **One connection, every workspace.** Your assistant reaches every workspace you belong to, with your role in each. You can't limit a connection to some workspaces: to keep an assistant out of one, leave that workspace or disconnect the assistant on the **AI connections** page. - **Your current workspace stays yours.** Your assistant works in your current workspace unless you name another, and it never changes the workspace you see in Roasby. - **Creating workspaces, inviting people and changing roles** are done in Roasby on the web. ## Confirmations Your assistant is told to show you every change and ask you before it makes it, and each change needs a preview first. The preview proves your assistant checked the change, not that you agreed: an assistant could run the preview and the change in one go. Many AI apps also ask you before they run a tool that changes something, so read that prompt before you approve it. Every change is in the [change log](/docs/change-log), and most can be reverted. ## Account states - **Reconnect needed:** the ad account is read-only until an owner or admin reconnects it on the [Ad accounts](/docs/ad-accounts) page. - **Read-only: over the limit:** the ad account stops syncing and can't be changed until an owner or admin makes it active. A person can still revert earlier changes on the web; your assistant can't. - **Read-only: set by support:** every change, reverts included, is refused until support allows changes again. Write to support@roasby.com. --- # Troubleshooting > Fixes for the problems people run into most, from an ad account that needs reconnecting to a change the guardrails refused. Each problem below says what you see, why it happens and what to do. If yours isn't here, see [Get help](#get-help). ## Sign-up says to use a permanent email address **Why:** Roasby doesn't accept temporary or disposable email addresses (such as Mailinator), because the account's emails (sign-in codes, alerts, the weekly report and billing) must reach you. **Fix:** sign up with your work or personal email address, or with a Google account on one. ## An ad account shows Reconnect needed **Why:** Roasby's access to the ad platform ended. You removed Roasby in your Google or Microsoft account settings, changed your password or deleted the ChatGPT Ads API key, or the person who connected the login left the workspace. **Fix:** an owner or admin opens **Ad accounts**, selects **Reconnect** and signs in again (for ChatGPT Ads, pastes a new key of the same account). Until then the account is read-only and doesn't sync. See [Reconnect needed](/docs/ad-accounts#reconnect-needed). ## A sync failed **Why:** the ad platform refused or didn't answer Roasby's read. The account shows the reason under **Last synced**, and your assistant sees it as `last_sync_error` in `list_ad_accounts`. **Fix:** - Read the reason. If it says access ended, reconnect the account (see above). - Otherwise select **Sync now** on the account, or ask your assistant to sync it (`run_ad_account_sync`). **Sync now** shows when it is available again. - If it keeps failing, [get help](#get-help). ## The numbers look old **Why:** Roasby answers from a synced copy of each ad account, so numbers are as fresh as the account's last sync. Periods on the dashboard end **yesterday**, and ad platforms keep adding late conversions for a few days. **Fix:** - Check **Last synced** on the account, then select **Sync now** to read it at once. - Changes you made in the ad platform itself (or in Google Ads Editor) show after the next sync. - A [weekly report](/docs/weekly-report) keeps the numbers it was sent with; ask for current ones (`get_performance_summary`). See [Syncing](/docs/ad-accounts#syncing). ## A change failed because an item was removed **Why:** the keyword or ad group was removed in the ad platform after Roasby's last sync, so the platform no longer has it. The change log says "no longer has this item". **Fix:** nothing to do: after a bid change, pause or enable Roasby marks it removed in its copy at once (otherwise the next sync does), so the next preview leaves it out, and the other items of the same change were sent. Ask your assistant to preview the change again if you still want it. ## A change was refused by the guardrails **Why:** the change is beyond the ad account's guardrails: above the max daily budget or the max bid, or a bigger rise than the max change per step allows (cuts are never limited, except a target ROAS, whose fall counts as a rise). The preview says which one. **Fix:** - Make a smaller change, or several steps. For bids and bid adjustments, ask your assistant to limit the change to the guardrails: it takes the largest step allowed. - Or raise the guardrail yourself: an owner or admin opens **Ad accounts → Guardrails**. Your assistant can never change a guardrail. Your assistant lists the steps only a person can do in `user_actions`, with a link. See [Budget and bid guardrails](/docs/safety-model#budget-and-bid-guardrails). ## I can't change ads in this workspace **Why:** you are a **member**, and members only read unless the workspace allows them to change ads. **Fix:** ask an owner or admin to turn on **Allow members to change ads** in **Workspace settings**, or to make you an admin. Your assistant checks this with `get_current_workspace` (`can_change_ads`). See [Who can change ads](/docs/workspaces#who-can-change-ads). ## An ad account shows Read-only: over the limit **Why:** the workspace has more ad accounts than it can keep active. The extra accounts keep their data but stop syncing and can't be changed. **Fix:** an owner or admin chooses which accounts stay active with **Make active** on **Ad accounts**, or asks the assistant (`preview_activate_ad_account`, then `activate_ad_account`). A person can still revert earlier changes on the web. See [Limits on ad accounts and members](/docs/ad-accounts#limits-on-ad-accounts-and-members). If your workspace has a monthly allowance of ad changes and used it up, new changes are refused until the count starts again on the 1st. Reverts, reports and previews keep working. ## An ad account shows Read-only: set by support **Why:** Roasby support made the account read-only, for example during a payment dispute or at your request. **Fix:** it keeps syncing and reporting, but every change, reverts included, is refused until support allows changes again. Write to support@roasby.com. ## My assistant doesn't see Roasby **Why:** the connection is missing, signed out or turned off in this chat. **Fix:** 1. Check that Roasby is added in your AI app with the address `https://roasby.com/mcp`, and turned on for this chat. 2. In Claude Code, run `/mcp` and choose **Authenticate** for Roasby. 3. Open **AI connections** in Roasby. If your assistant isn't listed, or shows **Not used recently**, add Roasby again and approve the connection. 4. Ask *"Which Roasby workspace am I in?"*: your assistant should call `get_current_workspace`. See [Connect your AI](/docs/connect-your-ai). ## Google Ads refuses every campaign change **Why:** Google Ads asks each campaign to declare whether it is EU political advertising. Until every campaign in the account has declared it, Google refuses every campaign change there. The preview names the campaigns, and a refused change says why in the [change log](/docs/change-log). **Fix:** declare it for those campaigns (or the whole account) in the Google Ads web interface, then try again. Roasby declares it for each campaign it creates, after asking you. See [EU political advertising](/docs/creating-campaigns#eu-political-advertising). ## A new campaign stays off **Why:** a campaign whose daily budget is above the max daily budget stays off, and so does one that was only partly created, until a sync shows an ad in it. A new ad account has no max daily budget until you set one, so your assistant can't create campaigns in it. **Fix:** set the max daily budget on **Ad accounts** (**Set it to create campaigns**), or lower the campaign's budget. See [Everything new starts paused](/docs/safety-model#everything-new-starts-paused). ## Get help - Open **Support** in your user menu, or [Support](/support), for the contact form and email address. - Or ask your assistant to write to support for you: it previews the message (`preview_create_support_request`) and sends it after you confirm (`create_support_request`). You get a reference to quote, and the team replies by email within 2 business days. - Search these docs, or ask your assistant: it reads them with `search_docs` and `get_doc`. --- # Glossary > Short definitions of the ad platform and Roasby terms used in these docs, from ROAS and Quality Score to guardrails and user actions. Short definitions of the terms these docs use, with a link to where each one is explained. ## Ad terms - **ROAS** (return on ad spend): conversion value divided by spend. A ROAS of 4 means 4 of value for every 1 spent. See [Dashboard](/docs/dashboard#performance). - **Impression share**: the share of the searches your search campaign could show for where it did show. What it missed is lost to rank (bid, ad quality, competition) or to budget. See [Impression share](/docs/campaigns#impression-share). - **Quality Score**: the ad platform's score from 1 to 10 for how relevant a keyword, its ads and landing page are. See [Quality Score and first page bid](/docs/campaigns#quality-score-and-first-page-bid). - **First page bid**: the bid the ad platform estimates your ad needs to show on the first page of results. See [Quality Score and first page bid](/docs/campaigns#quality-score-and-first-page-bid). - **Search term**: what a person actually typed before your ad showed. It can differ from your keyword. See [Search terms](/docs/search-terms). - **Negative keyword**: a word or phrase that stops your ads from showing for searches that contain it. See [Search terms](/docs/search-terms#excluding-a-search). - **Conversion action** (Google Ads) or **conversion goal** (Microsoft Ads): something valuable a person does after a click, such as a purchase, that the ad platform counts. Primary ones count toward bidding. See [Conversions](/docs/conversions). - **Bidding strategy**: how a campaign sets its bids, by hand (manual cost per click) or automatically toward clicks, conversions or conversion value. See [Bidding and goals](/docs/bidding-and-goals). - **Learning period**: the one to two weeks after a bidding change in which automated bidding learns again, so results can swing. See [Bidding and goals](/docs/bidding-and-goals). ## Roasby terms - **Workspace**: the place that holds ad accounts and the people who work on them, each with a role. See [Workspaces](/docs/workspaces). - **Ad account**: one Google Ads, Microsoft Ads or ChatGPT Ads account connected to a workspace. See [Ad accounts](/docs/ad-accounts). - **Sync**: Roasby reading an ad account into its own copy, on a schedule or with **Sync now**. Numbers are as fresh as the last sync. See [Syncing](/docs/ad-accounts#syncing). - **Guardrail**: a limit people set on each ad account (max daily budget, max bid, max target CPA, min target ROAS and the max rise per step) that a change must stay within once it is set; cuts are never held to the step, except a target ROAS, whose fall counts as a rise. See [Budget and bid guardrails](/docs/safety-model#budget-and-bid-guardrails). - **Max bid change per step**: how far, in percent, one change may raise a bid; a larger rise takes several steps, and a cut takes none. See [Budget and bid guardrails](/docs/safety-model#budget-and-bid-guardrails). - **Paused by default**: everything Roasby creates (campaigns, ad groups, ads, keywords) starts paused, so nothing spends until you enable it. See [Everything new starts paused](/docs/safety-model#everything-new-starts-paused). - **Preview and confirmation token**: before any change, your assistant previews it and gets a token that works once, for 10 minutes, for that exact change. See [Your assistant previews every change](/docs/safety-model#your-assistant-previews-every-change). - **Batch**: many items of one ad account changed together, with one preview, one confirmation and one revert. See [Batches](/docs/safety-model#batches-many-items-in-one-change). - **Revert**: a new change that puts back the value before an earlier change, or pauses what it created. See [Change log](/docs/change-log#revert-a-change). - **`user_actions`**: the steps only a person can do, listed in a tool's result with what, why, where and a link. Your assistant explains them and never says it did them. See [Steps only a person can do](/docs/safety-model#steps-only-a-person-can-do). --- # How to run ChatGPT Ads > Set up a ChatGPT Ads account, structure your first campaign, write your ad and read the results, step by step. ChatGPT Ads shows your ad next to relevant conversations in ChatGPT. It works differently from search ads, so this guide walks through the setup and the decisions that matter on a first campaign. Still deciding whether to run it? Read [ChatGPT Ads vs Google Ads](/guides/chatgpt-ads-vs-google-ads) first. ChatGPT Ads is still young and in beta, and details change quickly. The facts here were checked on the date above. Before you spend money, confirm them in [OpenAI's help center](https://help.openai.com/en/articles/20001047-ads-in-chatgpt) and [ad policies](https://openai.com/policies/ad-policies/). ## Check that you can advertise Two things decide this. - **Your country.** Ads Manager opens country by country. Creating an account does not give you access before your country is supported. - **Your category.** OpenAI limits which businesses can advertise, and some health, financial and legal categories are restricted or not allowed depending on the country. Read the ad policies first, so you don't build a campaign that can't run. It also helps to know who sees the ads. They can appear for people on the Free and Go plans, not on Plus, Pro, Business, Enterprise or Edu. ## Set up your account 1. Go to [ads.openai.com](https://ads.openai.com) and sign in with an OpenAI account, or create one. 2. Enter your website if you want Ads Manager to draft a first ad, or skip this and build the campaign yourself. 3. Check your account, brand and legal names, because your advertiser name fills all three at first. 4. Add billing. Campaigns can't deliver without it. Each advertiser needs a separate account. You can invite teammates as Admin, Member or Viewer. ## Understand the structure A campaign has three levels. | Level | What you set there | | --- | --- | | Campaign | Objective, budget, dates and targeting | | Ad group | Bids and context hints, around one theme | | Ad | Title, body text, image and landing page | Keep one theme per ad group. If you sell running shoes and hiking boots, make two ad groups, so each can have its own hints and bid and you can see which one works. ## Write useful context hints Context hints describe the conversations, topics or keywords where your product may be relevant. They guide matching, but they are not exact keywords and they don't guarantee your ad appears in a specific conversation. Write them the way people describe a need, not the way you describe your product. "Choosing shoes for a first half marathon" tells the system more than "premium running footwear". This is the biggest change if you come from search. There are no search terms to review and no negative keywords to add, so you control relevance through hints, ad groups and your landing page. ## Write the ad An ad is a card with a title, short body text, an image and a destination URL. The API documents a minimum image size of 640 by 640 pixels. - **Answer the need in the title.** Someone reading the card is in the middle of a question. - **Be plain and specific.** Say what you offer and who it suits, and avoid absolute claims. - **Send people to the matching page.** A shoe ad should open the shoe page, not your home page. Ads and landing pages go through review before they run, using automated checks with some decisions passed to people. ## Set your budget and bid Budgets are set on the campaign, and bids on the ad group. You can bid per click, and OpenAI also offers conversion-optimized bidding, which relies on conversion tracking. Ad selection uses a relevance-weighted, second-price auction, so a relevant ad does not need the highest bid to win. OpenAI's help center has suggested starting click bids of $3 to $5. Treat that as a starting point and check the current advice, because it may change. For a first test, pick a daily budget you are comfortable losing while you learn. Run one or two ad groups rather than many, so the budget isn't spread too thin. ## Track and read your results Set up conversion tracking before you launch, or you'll only know what you spent and how many people clicked. Reports show impressions, clicks, spend and conversions. Conversions can include people who saw your ad without clicking, and the API's default attribution is a 30-day click window and a 1-day view window, so compare with other channels carefully. In the first weeks, look at three things: 1. **Cost per click**, compared with your search campaigns. 2. **Click rate per ad group**, which shows which hints and ads fit. 3. **Cost per conversion**, once you have enough conversions to compare. Change one thing at a time. If you edit the hints, the ad and the bid together, you won't know what helped. ## Manage it next to your other ads ChatGPT Ads has its own Ads Manager, so comparing it with search means switching between tools. [Roasby](/chatgpt-ads) connects ChatGPT Ads, Google Ads and Microsoft Ads in one place. You can ask your AI assistant how they compare, have it create a campaign that starts paused, and change budgets inside limits you set. ChatGPT Ads does not report conversion value, so ROAS isn't available for it in Roasby. --- # How to reduce Google Ads wasted spend > Find the searches and keywords that cost money without converting, exclude them safely and keep waste from coming back. Wasted spend is money spent on clicks that were never likely to become customers. Every search account has some. This guide shows how to find yours and cut it without blocking searches that do make you money. You can follow these steps in Google Ads directly. The last section shows how Roasby shortens them. ## Start with conversion tracking Check this first. Waste means spending without a result, so you can't measure it if results aren't recorded. In Google Ads, open **Goals**, then **Conversions**, and confirm that your main action is recording: a purchase, a lead form or a booking. If an account shows clicks and no conversions at all, the likely problem is tracking, not your searches. Fix that before you exclude anything. ## Pick a fair period Use at least the last 30 days. A shorter period can make a search look bad when it simply hasn't had time to convert, and people often convert a few days after they click. If you spend little, use 90 days, so you have enough data to judge. ## Review your search terms The search terms report shows what people typed before your ad appeared. This is different from your keywords, which are what you chose to bid on. 1. Open **Insights and reports**, then **Search terms**. 2. Sort by cost, highest first. 3. Add a filter for zero conversions. 4. Read the top 20 to 50 searches. Sort each one into a group: | Search | Example for a CRM company | What to do | | --- | --- | --- | | Unrelated | "crm developer jobs" | Exclude it | | Wrong intent | "free crm templates" | Exclude it if you don't serve that need | | Related but not converting yet | "best crm for small teams" | Keep it and improve the ad or page | | Your brand | Your company name | Keep it | | A competitor | A rival's name | Decide deliberately, because bidding on these can be a choice | ## Add negative keywords carefully A negative keyword stops your ad from showing for that search. [Google's help page](https://support.google.com/google-ads/answer/2453972) explains how the match types work: - **Broad** blocks searches containing all your words, in any order. - **Phrase** blocks searches containing your words in that order, with other words around them. - **Exact** blocks only that exact search. Three details catch people out. - **Negatives don't expand to close variants.** Excluding "flowers" does not exclude "flower", so add singular and plural forms yourself. - **Too many negatives can reduce your reach.** Google warns about this directly, so add what the data supports and stop there. - **Check before you exclude.** A search with no conversions in one campaign may have converted in another. Look across the whole account first. When you are unsure, start with exact match. It is the narrowest, so it can't block anything else. ## Look for repeated bad words Single searches can look small while one word costs you across many of them. If "jobs", "salary" or "free" keeps appearing in searches that never convert, that word is worth excluding on its own as a broad or phrase negative. This finds waste that a top 20 review misses, and it stops new searches containing that word before they cost you anything. ## Pause keywords that don't convert Search terms are only half of it. Sort your keywords by cost with zero conversions over the same period. A keyword with many clicks and no conversions is a candidate to pause. Don't judge a keyword on a handful of clicks, and don't pause one without checking its ad and landing page first. Sometimes the keyword is right and the page is wrong. ## Check the other causes Negative keywords only fix one kind of waste. If your spend still looks wrong, check these: - **Location settings.** Make sure you target people in your locations, not only people interested in them. - **Match types.** Very broad keywords bring in more unrelated searches. - **Landing pages.** Good clicks can still fail on a slow or mismatched page. - **Schedule.** If you can only serve customers at certain times, check whether you are paying for clicks outside them. ## Make it a habit Wasted spend comes back, because people keep searching in new ways. Review search terms every week or two, and keep a short note of what you excluded and why, so you can undo a mistake. ## How Roasby helps [Roasby's wasted spend audit](/use-cases/wasted-spend-audit) does the review for Google Ads and Microsoft Ads. It adds up what you spent without a conversion, lists the costliest searches and keywords, and suggests exclusions. It holds back when the data isn't reliable: it suggests nothing for an account with no conversions, and it skips searches that name your brand or converted elsewhere. On the web you approve each change, and most changes can be reverted. You can also ask your AI assistant: *"Find the search terms that wasted money last month and suggest negative keywords."* --- # What is a Google Ads MCP server? > How a Google Ads MCP server connects an AI assistant to your ad account, what the options are, and how to use one safely. A Google Ads MCP server lets an AI assistant such as Claude or ChatGPT read your Google Ads account, and sometimes change it. This guide explains how that works, what your options are, and what to check before you connect a real account. ## What MCP is MCP stands for [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro), an open standard for connecting AI applications to outside systems. Its own docs compare it to a USB-C port: one standard way to plug things in. Without it, an assistant only knows what you paste into the chat. With it, the assistant can call tools that fetch real data or take actions. ## What a Google Ads MCP server does The server sits between your assistant and the Google Ads API. 1. You ask: "Which campaigns spent the most last week?" 2. The assistant picks a tool from the server, such as one that reads campaign performance. 3. The server fetches the data from your account. 4. The assistant answers using your real numbers. So you don't need to know the Google Ads interface, or write reports by hand. ## Your options **Google's official server.** [Google's MCP server](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server) is open source and built for reporting on live account data. Google's docs describe it as read-only: it can't change bids or pause campaigns. Its [repository](https://github.com/googleads/google-ads-mcp) also lists optional tools for assets and labels, so check the version you install. You run it yourself and set up a Google Cloud project and credentials. It suits developers who mainly want reporting, and [Official server or hosted?](/guides/google-ads-mcp-official-vs-hosted) compares the two routes. **Community servers.** Many open-source servers exist, and some add write tools. Quality and safety vary, you run and update them yourself, and you are trusting that code with your account. Read the code before you connect a real account. **Hosted servers.** A company runs the server and you connect by signing in, usually with nothing to install. This is the simplest route, and [Roasby](/google-ads) is one of these. The trade-off is that you are trusting that company, so check how it stores your access and what it can do. ## What can go wrong A connected assistant is useful because it can act, and that is also the risk. Assistants make mistakes, and a misunderstood request can cost real money. - **Wrong change.** An assistant pauses your best campaign, or changes the wrong budget. - **Oversized change.** A typo or a misread number raises a budget far more than you meant. - **Deleted work.** A removed campaign often can't be brought back. - **Instructions hidden in data.** Text from outside, such as a search term, could try to steer the assistant. This is known as prompt injection, and it is why a person should approve changes. - **Leaked access.** Keys pasted into a config file or a chat can end up somewhere you didn't intend. ## What to check before you connect Read access carries little risk to your campaigns, and [Is it safe to give AI access to Google Ads?](/guides/is-it-safe-to-give-ai-access-to-google-ads) covers the wider question. Before you give any server write access, look for these: | Check | Why it matters | | --- | --- | | Changes are previewed | You see what will happen before it does | | A preview and a confirmation step before each change | The assistant is told to wait for you | | New campaigns start paused | Nothing spends until you choose | | No delete tools | A mistake can't remove your campaigns | | Budget limits sit outside the assistant | The assistant can't talk its way past them | | Every change is logged, and most are revertible | You can see what happened and usually reverse it | | Sign-in uses OAuth | No keys to copy, and you can revoke access | | Access is stored encrypted | A leak is less likely to expose your account | If a server can't answer these, start with read-only access. ## A safe way to start 1. **Start by reading.** Ask about performance and wasted spend for a few days, and check the answers against Google Ads. 2. **Try a small change.** Add one negative keyword, and see how the preview and the confirmation work. 3. **Set limits first.** Choose a maximum daily budget and a maximum change before you let an assistant touch budgets. 4. **Review the log.** Look at what changed each week until you trust the setup. ## How Roasby does it [Roasby](/google-ads) is a hosted MCP server for Google Ads, Microsoft Ads and ChatGPT Ads. You add one address to your assistant, sign in, and approve the connection. It follows the checklist above: your assistant reads freely, previews each change and is told to wait for your yes, new campaigns start paused, and there are no delete tools. The [safety model](/docs/safety-model) has the details, and [Connect your AI](/docs/connect-your-ai) shows the setup for each assistant. --- # Is it safe to give AI access to Google Ads? > What you actually hand over when an AI assistant connects to Google Ads, where the real risks are, and how to limit them. It can be, but the answer depends less on the AI than on what sits between it and your account. This guide looks at what you hand over when you connect an assistant, which risks are real, and how much access suits your situation. For how these servers work and how to compare them, see [What is a Google Ads MCP server?](/guides/what-is-a-google-ads-mcp-server). ## What you hand over Three separate things are involved, and people often treat them as one. - **Access to the account.** Google's API access uses one [`adwords` scope](https://github.com/googleads/google-ads-mcp) for reading and changing. A tool that asks for this scope is not limited to reading by Google, so any read-only promise has to come from the tool. - **Your data.** Whatever the assistant reads goes to the AI provider as part of your conversation. That can include campaign names, budgets and search terms, and for an agency, client data. Check how your AI plan handles conversations, and whether your client contracts allow it. - **Your spending power.** Anything that can raise a budget or enable a campaign can spend your money, and money spent can't be recovered, even when the setting can be put back. ## The risks that matter **Misunderstood requests are the likely one.** "Pause the bad campaigns" depends on what the assistant takes "bad" to mean. If it judges on a week of data or the wrong conversion action, it can pause something that works. Nobody needs to attack you for this to happen. **A wrong figure can look right.** Assistants write confidently, so a mistaken total reads like a correct one. Before you act on a number, check where it came from and which dates it covers, at least until you trust the setup. **Text in your data can carry instructions.** Search terms come from the public, so anyone can put words into your search terms report. If an assistant treats that text as a request, it might act on it. This is called prompt injection. The defense is a step that the text can't reach, such as limits held outside the assistant and a person approving each change. **Leaked access is the quiet one.** A key pasted into a config file or a chat can spread further than you intended. Sign-in through OAuth avoids copying a secret around, and it can be revoked later. ## How much access suits you Match the access to the account, not to how impressive the demo was. | Your situation | A sensible level | | --- | --- | | Curious, first week | Read only. Ask questions and compare the answers with Google Ads | | Your own small account | Changes with a preview, and a tight budget limit | | A large or fast-moving account | Reads and negative keywords first. Add budgets only after a few calm weeks | | Client accounts | Agree it with the client first. Keep a change log you can show them | Moving up a level should follow evidence from your own account. A good sign is several weeks of answers that matched the ad platform. ## Reduce the risk before you connect 1. **Use the smallest Google Ads role that works.** A login with [read only access](https://support.google.com/google-ads/answer/9978556) can't make changes, whatever a tool tries. It is the strongest limit for a first trial, because it doesn't depend on the tool. 2. **Set limits the assistant can't change.** A cap the assistant could raise by asking is only a suggestion. Look for limits that only a person can set. 3. **Read the prompt before you approve.** Approval only protects you if you read it. Check the account, the item and the value before and after. 4. **Review changes weekly.** Compare what changed with what you meant to change, in the tool's log and in the Google Ads change history. 5. **Know how to cut access.** You can remove a connected app in your [Google Account](https://myaccount.google.com/permissions). Try this once so you know where it is before you need it. ## When to say no Hold off if your conversion tracking is broken, because any assistant will then optimize toward bad numbers. Hold off too if you can't explain what a tool does when something goes wrong, or if a contract or regulation stops you sending account data to an AI provider. ## How Roasby handles this [Roasby](/google-ads) sits between your assistant and your ad accounts. The assistant never sees your ad platform access, it reads through tools, and each change has a preview step that returns a one-time token. It is told to show you the change and wait for your yes. Limits on budgets and bids are set by people on the web, so an assistant can read them but not loosen them. There are no delete tools, new campaigns start paused, and the change log shows who changed what. Most changes can be reverted, though money already spent can't be recovered, and a change made directly in Google Ads goes around these limits. The [safety model](/docs/safety-model) lists every rule. Your AI assistant is still software that can misread you, so keep reading what it proposes. --- # ChatGPT Ads vs Google Ads > How ChatGPT Ads and Google Ads differ in targeting, control, budget and reporting, and how to decide which one to test or fund. Google Ads answers a search someone typed. ChatGPT Ads appears next to a conversation someone is having. That difference shapes almost everything else: how you target, what you can control and how you read the results. ChatGPT Ads is young and in beta, and details change quickly. The facts here were checked on the date above. Confirm them in [OpenAI's help center](https://help.openai.com/en/articles/20001047-ads-in-chatgpt) before you spend money. This guide compares ChatGPT Ads with Google Search campaigns, not with Display, Video or Performance Max. ## The short comparison | | Google Ads (Search) | ChatGPT Ads | | --- | --- | --- | | Where the ad appears | On search results | Next to relevant conversations in ChatGPT | | Who can see it | People searching on Google | People on the Free and Go plans of ChatGPT | | How you target | Keywords with match types | Context hints, which guide matching | | How you exclude | Negative keywords | No negative keywords | | What you can review | The search terms behind your clicks | No search terms report | | Where bids sit | Depends on the bid strategy | On the ad group | | Availability | Open to most advertisers | Opens country by country | ## Targeting: words versus context In Google Ads, a keyword has a [match type](https://support.google.com/google-ads/answer/7478529). Broad is the default, phrase uses quotes and exact uses square brackets. The search terms report then shows what people really typed, so you can add [negative keywords](https://support.google.com/google-ads/answer/2453972) and steer away from the wrong traffic. ChatGPT Ads has none of that. You write context hints, which describe the topics and needs where your product may be relevant. They guide matching, but they don't guarantee your ad appears in a specific conversation. So the skill moves. On Google, much of the work is cleaning up after the fact, one search term at a time. On ChatGPT Ads, relevance is decided up front by your hints, your ad groups and your landing page. If traffic is off target, you rewrite the hints, and you won't see a list of what triggered the ad. ## Control and day-to-day work Google Ads gives you more levers, and years of tools around them, with [bid strategies](https://support.google.com/google-ads/topic/10286469) from manual CPC to target CPA and target ROAS. ChatGPT Ads has fewer. Budgets sit on the campaign and bids on the ad group. You can bid per click, and OpenAI also offers conversion-optimized bidding, which relies on conversion tracking. Fewer levers means a campaign is quicker to set up, and that there is less to adjust when it underperforms. ## Budget In our own testing through the API, ChatGPT Ads refused a daily budget below $25 for a campaign. OpenAI's help center has suggested starting click bids of $3 to $5. Both may change, so check the current figures. Google Ads doesn't set a similar campaign minimum, which makes small tests easier there. If you can only fund one small test, a tight Search campaign usually tells you more, because you can see which searches you paid for. ## Measuring results Conversion tracking matters on both, and neither should run without it. Comparing the two takes care for one reason: the numbers aren't counted the same way. ChatGPT Ads conversions can include people who saw the ad without clicking, and the API's default attribution is a 30-day click window and a 1-day view window. Google Ads has its own [conversion measurement](https://support.google.com/google-ads/answer/1722022) settings. Two platforms can each claim the same customer, so a side-by-side cost per conversion is a rough guide. Your own sales or lead records are the better judge. The two also reach people at different moments. Someone searching a product name is near a decision. Someone asking for advice in a chat may be earlier, so give that traffic time before you judge it on last-click sales. ## Which one to choose **Start with Google Ads** if you need leads now, people already search for what you sell, or your budget is small. **Test ChatGPT Ads** if your product takes some explaining, people ask for advice before they buy, your country and category are supported, and you can treat the budget as a test. For most businesses this isn't a choice of one or the other. Keep Google Ads as the base that captures existing demand, and give ChatGPT Ads a fixed test budget with a clear end date. Decide what would count as success before you start. The practical steps are in [How to run ChatGPT Ads](/guides/how-to-run-chatgpt-ads). ## Managing both Each platform has its own interface, so a comparison usually means switching between tabs and exports. [Roasby](/chatgpt-ads) connects [Google Ads](/google-ads) and ChatGPT Ads, plus Microsoft Ads, in one place, so you can ask your AI assistant how they compare and see them in one dashboard. --- # Google Ads MCP: official server or hosted? > Google's own MCP server compared with a hosted one, covering setup, Google Cloud access levels, what each can change and who each suits. Google publishes its own Google Ads MCP server, free and open source. So why would anyone use a hosted one? It comes down to who does the setup, what the server can change and who carries the risk. This guide compares the two types of server. If you are new to MCP, start with [What is a Google Ads MCP server?](/guides/what-is-a-google-ads-mcp-server). The facts about Google's server were checked on the date above against its [repository](https://github.com/googleads/google-ads-mcp) and [developer docs](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server). It changes often, so check both. ## The short comparison | | Google's server | A hosted server | | --- | --- | --- | | Who runs it | You, on your computer or your own cloud | The company behind it | | Setup | Google Cloud project, API access, OAuth, config | Add an address and sign in | | Mainly for | Reporting and analysis | Depends on the product. Many add changes | | Cost | Free software, plus your own hosting if any | Usually a subscription | | Who you trust | Google's code and your own setup | That company too | | Updates | You choose when to update | The company updates it for you | ## What Google's server does Its core tools list the accounts you can reach, read how the API's fields are structured, and run reports with GAQL, Google's query language. The two sources differ on writing. The developer docs describe it as read-only: it can't change bids, pause campaigns or create new assets. The repository's README lists extra tools for creating assets and managing labels, behind a propose-and-confirm step, and says to switch them off for a strictly read-only setup. Check which applies to the version you install, and turn off what you don't need. Neither source lists tools for budgets, pausing or new campaigns, so if you want an assistant to do those, you'll need something else. ## What setup involves To run Google's server, you need: 1. A Google Cloud project with the Google Ads API enabled. 2. An OAuth client or Application Default Credentials, with the `adwords` scope. 3. The server itself, usually run with `pipx`, or deployed over HTTP to a service such as Cloud Run. 4. A configuration entry in your AI client. 5. The right API access level for your project. If you read older tutorials, note that [developer tokens were sunset on September 9, 2026](https://developers.google.com/google-ads/api/docs/api-policy/access-levels). Access levels now belong to the Google Cloud project, and Google's developer docs say the latest version of the server doesn't require a token, although its README still mentions one for some setups. ## Access levels matter more than people expect Enabling the API gives you Test access, which only works on test accounts. For a real account you need more: | Level | Real accounts | Operations a day | How you get it | | --- | --- | --- | --- | | Test | No | 15,000 on test accounts | Given when you enable the API | | Explorer | Yes | 2,880 | Apply; usually an automated review | | Basic | Yes | 15,000 | Brand verification, then apply | | Standard | Yes | Unlimited | A detailed manual audit | For one person reporting on one account, Explorer is often enough. A team, an agency with many accounts or frequent scheduled reports can reach its limit, and moving up takes verification or an audit. A hosted server uses its own Google access, so you don't apply for any of this. ## When Google's server is the better fit - You are comfortable with Google Cloud, OAuth and a terminal. - You want reporting and analysis, not changes to campaigns. - You want the code on your own machine, with no extra company between you and Google. - You want to build your own tools on top, or you already have a Cloud project. ## When a hosted server is the better fit - You want to be working in minutes, on the web or a phone as well as in an editor. - People who don't use a terminal need access, such as a client or a marketing teammate. - You want your assistant to pause, change budgets or add negative keywords, inside limits you set. - You want more than Google Ads in one conversation, or a shared log of who changed what. ## What to check on a hosted server A hosted server adds a company to your chain of trust, so ask more of it. How does it store your access? Can its limits be changed by the assistant, or only by a person? Is there a log of changes? What happens to your data when you leave? The [checklist in our MCP guide](/guides/what-is-a-google-ads-mcp-server) covers this in full, and [Is it safe to give AI access to Google Ads?](/guides/is-it-safe-to-give-ai-access-to-google-ads) helps you decide how much access to give. ## Where Roasby fits [Roasby](/google-ads) is a hosted server for Google Ads, Microsoft Ads and ChatGPT Ads. If you only want Google Ads reports and enjoy the setup, Google's server may be all you need. Roasby is for people who want their assistant to make changes, with a preview step, limits set by people and a change log. It works with [Claude](/integrations/claude), [ChatGPT](/integrations/chatgpt), [Cursor](/integrations/cursor) and [Codex](/integrations/codex).