Get ad-server connection

GET /api/v2/storefront/inventory-sources/{sourceId}/esa Returns the connection state for an ad-server-backed (MANAGED_SALES_AGENT) source: enabled/disabled state (deactivatedAt), upstream endpoints, the non-secret ad-server config view, the most recent failure (lastErrorCode/lastError), and cached inventory-sync state.

Request

curl https://api.interchange.io/api/v2/storefront/inventory-sources/retail-gam/esa \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`sourceId`	string (path)	Yes	Storefront-scoped inventory source ID

Response

{
  "id": "550199",
  "name": "Retail video",
  "customerId": 4210,
  "tenantId": "tnt_retail_gam",
  "mcpUrl": "/mcp/",
  "a2aUrl": "/a2a",
  "adServer": { "type": "google_ad_manager", "networkCode": "12345678" },
  "serviceAccountEmail": "retail-gam-4210@scope3-esa.iam.gserviceaccount.com",
  "lastError": null,
  "lastErrorCode": null,
  "lastTestedAt": "2026-05-02T09:14:00Z",
  "provisionedAt": "2026-04-25T12:10:00Z",
  "deactivatedAt": null,
  "createdAt": "2026-04-25T12:05:00Z",
  "updatedAt": "2026-05-02T09:14:00Z",
  "inventorySync": {
    "status": "success",
    "lastRunAt": "2026-05-02T08:00:00Z",
    "completedAt": "2026-05-02T08:03:00Z",
    "itemCount": 1840,
    "error": null,
    "updatedAt": "2026-05-02T08:03:00Z"
  }
}

The connection is enabled unless deactivatedAt is set (null means enabled); whether it is live and sellable is derived from the status endpoint (operational.isLive), not from a field on this response. name is the seller-facing linked inventory-source name (or null when no active source is linked). adServer is the non-secret config view and never contains credentials. lastErrorCode classifies the most recent failure (ADAPTER_NETWORK_NOT_FOUND, ADAPTER_PERMISSION_DENIED, ADAPTER_INVALID_CREDENTIALS, ADAPTER_INVALID_CONFIG, ADAPTER_CONNECTION_FAILED, or INTERNAL_ERROR), with the human-readable detail in lastError. inventorySync is null until the first sync signal lands.

What `lastTestedAt` proves, and what it does not

lastTestedAt is when a connection test last ran against this connection. Every probe moves it — one that passed, one that the ad server refused, and one that never reached the ad server at all. null means nobody has ever probed this connection. It answers “when did anyone last check”, not “does this work”. Nothing in this response contacts the ad server, so a connection reporting connected in its status while lastTestedAt is null has never been verified against the live ad server. Only the result of a probe you just ran shows the current state. lastError/lastErrorCode usually describe that last probe, with one exception: while an ad-server configuration or FreeWheel execution-currency change is being applied, they describe that work instead. These states use ADAPTER_CONFIG_* or EXECUTION_CURRENCY_* codes. A probe never overwrites one of these codes, so a recent lastTestedAt does not mean the configuration change has completed. For FreeWheel, adServer.executionCurrency is the current declared currency or null for a legacy source that still needs one. Use Set FreeWheel execution currency to add or change it without resending write-only credentials.

Errors

401 UNAUTHORIZED — missing or invalid API key.
404 NOT_FOUND — no ad-server-backed source with this sourceId.

See Errors for the full error contract.

Inventory source tasks

All operations

Get status

Operational snapshot

Replace ad-server config

Set the ad-server config

Set FreeWheel execution currency

Add or change the currency without replacing credentials

Test connection

Probe upstream reachability

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Get ad-server connection

Request

Parameters

Response

What `lastTestedAt` proves, and what it does not

Errors

Inventory source tasks

Get status

Replace ad-server config

Set FreeWheel execution currency

Test connection

​Request

​Parameters

​Response

​What lastTestedAt proves, and what it does not

​Errors

​Related

Inventory source tasks

Get status

Replace ad-server config

Set FreeWheel execution currency

Test connection

Request

Parameters

Response

What `lastTestedAt` proves, and what it does not

Errors

Related