> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin ESA sync recovery

> Recover or force-start embedded sales agent sync streams during Scope3 support operations

`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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.                          |

## Related operations

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.