Admin ESA sync recovery

POST /api/v2/admin/embedded-sales-agents/{esaId}/syncs/{syncType}/recover This endpoint is a Scope3 super-admin operation for recovering embedded sales agent sync streams. It is not a normal storefront API for sellers, but its behavior can affect seller-visible diagnostics when a managed ad-server source has a stuck, stale, or never-started sync. Use recovery when the upstream ESA has stopped making progress on a specific stream and the operator has confirmed the stream should be restarted. Do not use it as a generic retry for every health warning: storefront status refreshes and source diagnostics are the seller-facing tools for ordinary checks.

Sync types

The syncType path parameter accepts:

Sync type	Notes
`inventory`	Ad-server inventory and product source data
`custom_targeting`	GAM custom-targeting keys and values
`advertisers`	GAM advertiser cache used by buyer routing
`reporting`	Upstream reporting sync state
`signal_coverage`	Upstream signal coverage sync state
`pricing_availability`	Wholesale pricing and availability sync state
`media_buy_status`	Re-checks non-terminal media buys (`pending_approval`, `pending_start`, `paused`) against the ad server and corrects drifted statuses

Request body

{
  "mode": "stale_only",
  "startAfterRecovery": true,
  "reason": "Recover a stale pricing availability sync after support triage.",
  "dryRun": false
}

Field	Type	Required	Notes
`mode`	`stale_only` or `force`	No	Defaults to `stale_only`. `stale_only` recovers only when the upstream run is past its stale threshold. `force` starts or replaces the stream even when there is no stuck run.
`startAfterRecovery`	boolean	No	Defaults to `true`. When true, the ESA starts a replacement run after recovery.
`reason`	string	No	Operator-facing audit note explaining why recovery was run.
`dryRun`	boolean	No	Defaults to `false`. When true, reports what would happen without mutating upstream state.

Use mode: "force" only after explicit operator confirmation. Force recovery is the path for never-run streams such as pricing_availability where a generic ESA refresh is not enough to start the stream.

Response

{
  "tenantId": "tenant_123",
  "syncType": "pricing_availability",
  "action": "force_recovered_and_started",
  "mode": "force",
  "dryRun": false,
  "newSyncRunId": "run_01J2...",
  "previousSyncRunId": null,
  "startedAt": "2026-07-10T10:55:55Z",
  "message": "Force recovered and started pricing availability sync."
}

action can be:

Action	Meaning
`noop_no_run`	No matching run exists and the request did not force a start.
`noop_not_running`	The latest run is not currently running.
`noop_not_applicable`	The adapter has no ad-server pricing sync to recover (for example, a non-GAM adapter).
`noop_recent_running`	A run is in progress and has not crossed the stale threshold.
`recovered`	A stale run was recovered.
`recovered_and_started`	A stale run was recovered and a replacement run started.
`force_recovered`	The stream was force-recovered without starting a replacement.
`force_recovered_and_started`	The stream was force-recovered and a replacement run started.

The admin refresh endpoint, POST /api/v2/admin/embedded-sales-agents/{esaId}/sync/refresh, asks the ESA to refresh the standard managed-source streams. For GAM-backed ESAs, that covers inventory, custom targeting, advertisers, and media_buy_status. It does not force-start wholesale pricing_availability; use the sync recovery endpoint with syncType: "pricing_availability" and mode: "force" for that case.

Getting Started

Operating Your Storefront

Inventory Sources

Real-Time Targeting (TMP)

Approvals & Reviews

Buyer Onboarding

Demand & Signals

Proposals & Agents

Buyer Routing

Analytics & Activity

Billing

Account

Sync types

Request body

Response

​Sync types

​Request body

​Response

​Related operations

Sync types

Request body

Response

Related operations