Goals
List Product Goals
Lists the product goals currently in force (open goals), one row per product and scope (a specific ad account, or all accounts). Sorted newest first by `effective_from`, then by ID. Paginated, 10 per page by default (max 200).
Get Goal Settings
Returns the tenant's goal mode. `suggest` (default): the goal advisor only creates suggestions that a person accepts or dismisses. `auto`: open suggestions are applied automatically on the nightly advisor run, each switch recorded with its reason.
Update Goal Settings
Sets the tenant's goal mode. The change is recorded in the activity log.
Bulk Set Product Goals
Sets one goal on up to 1000 products at once. Each product is processed on its own with the same rules as setting a single product's goal, so a product blocked by a guardrail does not stop the others; the response reports each product's outcome.
Get Product Goal
Returns a product's goal picture: the effective goal across all accounts (`effective_goal`, Profit when none is set), the open goals per scope (`open`, the all-accounts goal first, then per account), the full goal history newest first (`history`, up to 100 entries, every switch with its reason), and the advisor's open suggestions for the product (`suggestions`). The nested `product` and `account` objects are null in this response.
Set Product Goal
Sets the advertising goal for one product, for a single ad account (`ad_account_id`) or for all accounts (omit it). Setting a goal closes the product's currently open goal for that scope (it stays in the history) and opens a new one with the reason recorded; if the open goal already has the same goal and params, it is returned unchanged.
Reset Product Goal
Resets a product's goal to the default (Profit) for one ad account (`ad_account_id` query parameter) or for all accounts (omit it). The reset is recorded in the goal history like any other switch, with the reason 'Reset to the default goal (Profit).'; if the open goal is already Profit with no params it is returned unchanged.
Set Product Goal From Product
Alias of `PUT /api/advertising/goals/products/{product}` with identical behaviour, body and response.
List Goal Suggestions
Lists goal suggestions produced by the goal advisor, each with its reason, a one-line `headline` and the `evidence` behind it (days of cover, units available, days since first sale, aged units, oldest age in days, the next long-term-storage-fee date and units, the next inbound purchase order number; a dismissed suggestion also carries `dismissed_reason`, and one that auto mode could not apply carries `auto_blocked`). Only open suggestions are returned unless `status` is given. Sorted newest first by ID. Paginated, 10 per page by default (max 200).
Refresh Goal Suggestions
Starts the goal advisor now instead of waiting for the nightly run. Runs asynchronously as a tracked background job and returns its `tracked_job_log_id` for progress polling. The advisor first ends Launch goals whose launch window is over, then assesses every product advertised in the given ad accounts (or every selected ad account when `ad_account_ids` is omitted or empty) and writes new suggestions; when the goal mode is `auto`, suggestions are applied straight away. Suggestions a person dismissed recently are not repeated.
Bulk Accept or Dismiss Goal Suggestions
Accepts or dismisses up to 1000 goal suggestions in one call. Accepting sets the product's goal to the suggested one (with the suggestion's reason, recorded as set by the advisor); dismissing closes the suggestion, storing the optional `reason` in its evidence.
Bulk Accept Goal Suggestions
Accepts up to 1000 goal suggestions in one call; each product switches to its suggested goal with the suggestion's reason.
Accept Goal Suggestion
Accepts an open goal suggestion: the product's goal for the suggestion's scope is set to the suggested goal (recorded as set by the advisor, with the suggestion's reason and the default params for that goal), and the suggestion is marked accepted. No request body.
Dismiss Goal Suggestion
Dismisses an open goal suggestion, optionally saying why. The reason is stored in the suggestion's `evidence.dismissed_reason`; the advisor will not repeat the same suggestion for a while.