Custom metrics from Google Sheets

A custom metric lets an AdOps rule act on a number Meta never sees. You point AdOps at a Google Spreadsheet ID, a sheet name, a lookup column and a value column; at evaluation time AdOps finds the row whose lookup column matches the campaign id and returns that row’s value column as the metric.

What is this for?#

Margin, cost of goods, offline revenue, a stock level, a per-campaign target your finance team maintains. Any number a human keeps in a spreadsheet can become a rule condition, or a budget amount, or a token stamped into a campaign name.

The typical shape is one row per campaign:

campaign_id	target_roas	margin
23851234567890123	2.5	0.42
23851234567890456	3.0	0.31

With Column ID set to campaign_id and Value Column set to target_roas, a rule can compare live Purchase ROAS against a target that differs per campaign and that your team edits in a spreadsheet.

Creating the metric#

Open Custom Metrics under Rule in the sidebar and press + Add New. The form is two cards.

Basic Information takes the Metric Name, the Google Spreadsheet ID and a Description. The spreadsheet field is hinted “Found in the spreadsheet URL” with the helper “Leave empty if not using Google Sheets”.

Metrics Configuration starts with a Data Source Type select — “Select source type” or “Google Sheets”. Choosing Google Sheets reveals Sheet Name, Column ID and Value Column.

Press Create Metric to save, or Save as Draft to come back to it. In edit mode the header reads Update Custom Metrics, the primary button becomes Update Metric, and Save as Draft is hidden.

When validation fails#

AdOps reads the sheet before saving and checks that both columns exist. If they do not, a red Google Sheets Validation Failed modal lists each problem — for example that a Column ID was not found in a named sheet, followed by the columns that actually are there — plus a How to fix checklist.

The two failures worth checking first are a spreadsheet AdOps cannot open, and a column name that does not match the sheet’s header exactly, including case and trailing spaces.

How the number is read at run time#

AdOps fetches the sheet through Google’s direct CSV export endpoint with a 30-second timeout. If that fails it retries through the Sheets API, and if Google is unreachable entirely it serves the last rows it stored for that sheet.

Rows are also held in an in-memory cache keyed by spreadsheet and sheet name, with a two-minute window measured from the last access. That is what lets hundreds of campaigns in one batch share a single spreadsheet read. It also means the window can keep extending under continuous access, so treat a custom metric as a number that updates in minutes, not seconds.

Because the MongoDB fallback exists, a spreadsheet whose sharing has been revoked can keep resolving from stored rows. After changing a sheet’s permissions, re-save the metric in AdOps to confirm it still validates.

Using it in a rule#

Every metric picker in the rule builder has two tabs: Meta Ads and Custom metrics. A custom metric can be:

• the metric in a condition,
• the compared metric in a metric-to-metric condition,
• a budget action’s value, by setting value_3 to custom_metric,
• a token in an Add to name template, written {custom_metric|<id>}.

Saved rules resolve stored ids back to metric names, so a task summary reads “Blended ROAS” rather than a database id, and the same substitution happens in the execution log. An id that no longer resolves renders in red — that is your signal that a metric was deleted while a rule still refers to it.