> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/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 Apostra support operations

`POST /api/v2/admin/embedded-sales-agents/{esaId}/syncs/{syncType}/recover`

This endpoint is an Apostra 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.