Lookouts reference
Every grain, trigger, action and guard, in one place.
Grains
What a Lookout looks at. Nine, in three families.
Advertising — campaign, ad_group, target, ad, search_term, negative
Catalogue — product, variant
Absence — gap
These are the words you write. Listing is the internal name of the row a product is stored in and design is the artwork; neither is a grain you can type.
gap is the one that surprises people: it selects rows that do not exist. A design that sells in the US and is not listed in Germany is a gap, and there is no row anywhere to find it with. Nothing else in the language can ask that question.
Triggers
Four, and all four are floors rather than clocks:
| Trigger | Meaning |
|---|---|
manually | Only when you press Run. |
on publication | After a publish run finishes. |
daily | Not more often than daily. |
weekly | Not more often than weekly. |
The background worker sleeps when Chrome is idle, so a scheduled Lookout runs the next time the browser is awake after the interval has passed. Days are counted in Los Angeles report days, which is the boundary Amazon's own reporting uses.
Actions
Eighteen. A Lookout proposes exactly one per row — either the one action it carries, or, when it carries a ladder, whichever rung claims that row first. Never two about the same row.
Advertising (13) — bids and budgets, enabling and pausing, negative keywords and negative products, promoting a search term to a keyword, un-negating, adding a product target, adding a product to an ad group, and splitting a shared campaign.
Catalogue (3) — setting a price, editing attributes, adding a product. All three currently compile, run and preview, then decline to queue. The restriction is on the rule, not on the change: a price you stage by hand from the Catalog queues and applies normally. An advertising proposal can be walked back — paused, re-enabled, raised again — and a catalogue one often cannot, so a rule is not yet allowed to make them for you.
Local (2) — report only, and tagging a product. Neither touches Amazon.
There is no delete. It is not a verb the language has, deliberately — a rule that can remove things is a rule whose worst day is unrecoverable.
Guards
Three interlocks can hold a proposal back after the condition matched:
| Guard | What it means |
|---|---|
price_change_evidence | The price moved inside the period this rule judges, so the ACoS it would act on measures two different prices. |
ads_are_feeding_it | Advertising is feeding the product — thin organic sales are not the whole story. |
out_of_season | The product is out of its declared season. |
None applies to local_report_only.
A fourth reason is easy to confuse with the second: stale_data means the data itself has not settled yet. ads_are_feeding_it is a judgement about the product; stale_data is a judgement about the numbers.
Held-back reasons
Sixteen in total, each with its own label in the interface. Besides the three guards, they cover cooldowns, a proposal you declined recently, a row that is not addressable, a change that would change nothing, a row already in the queue, a row the selection never reached, blocked catalogue actions, unbounded selections, and values the rule could not compute.
If a run holds everything back, the label tells you which. It is never a generic failure.
Guardrails
The sixth part of a rule, and the one most people forget they have. Seven, written after with:
| Guardrail | What it does |
|---|---|
min_clicks | Ignore rows below a click count. |
min_orders | Ignore rows below an order count. |
min_spend | Ignore rows below a spend. |
max_per_run | Cap how many proposals one run may make. |
cooldown | Days before the same row may be proposed again. |
max_change | Cap the size of a single change, as a percentage. |
fresh_data | Refuse to act unless the data is current. |
max_per_run is the one that interacts with the limit below.
Limits
An uncapped run stops at 5,000 rows rather than truncating, and reports itself as deferred rather than as a failure — the rule is not wrong, it is unbounded. Give it a max_per_run and it runs whatever it matched, however many that is.
A rule that selects more than five thousand rows and says nothing about how many it may act on is a rule that has not been narrowed, and quietly acting on the first five thousand would be worse than stopping.
The three surfaces
Lookouts can be written in a visual builder, as text, or by an assistant. New lookout opens on the templates, with the builder, the editor and paste as the three blank starts beneath them; a rule somebody pasted, or one that nests, wants the editor; most others do not.
Anything the builder cannot draw opens in the editor. It is the same rule either way.
What an assistant can compose
A connected assistant can build a lookout for you from the same vocabulary the builder uses — not only from a template. What it composes lands on your Lookouts page like any other: you read it, edit it, switch it on and delete it exactly as you would one you wrote. Creating one puts nothing in your Publish queue; what reaches the queue is what the lookout finds once it is watching.
They are tagged from your assistant in the list, so you can always tell which ones you did not write. An assistant may hold at most five of them switched off at once.
It composes from a narrower vocabulary than you have, and the narrowing is deliberate rather than technical:
| It can | It cannot |
|---|---|
Every metric and fact, with any period, including a previous period for "worse than it was". | Match text — contains, starts with, and the rest. Those take a word somebody chose, and a lookout's rule is stored in your data and read back to the assistant later. "Exclude anything with my brand in it" stays yours to write. |
| Compare a metric against a number, or against another metric with a multiplier. | Name a lookout. The engine names it from the rule itself, because that name is drawn beside the Approve button. |
Do arithmetic — spend − ad_sales × 0.35, the money question no column holds. Up to two computed values, named v1 and v2 for you. | Build one computed value out of another, or use case and lists inside one. |
| Set the guards, and it is required to set a per-run cap and a cooldown. | Ask about a row's parent or the rows inside it, or nest condition groups. |
| Up to three actions as a ladder — ordered, first match wins, one verb per row: "pause the worst, ease the merely disappointing, leave the rest" is one lookout. The verbs are the same nine your assistant could already propose one at a time, plus report-only. | Put the same verb on two rungs. Two rungs that both lower a bid are one verb with two amounts, which is a case in the value — a builder job. |
Everything it cannot compose, it is told it cannot, and why — so it should tell you which one thing is a builder job rather than saying the whole idea is impossible.