GET /v1/projects/:projectId/ads/ad-accounts

Returns every ad account connected to the project across Meta, TikTok, and Apple Search Ads. Each account carries the platform-native id and current credential health. Layers' ad platform integrations are bring-your-own: partners connect their own ad accounts via OAuth, and platform billing runs against the partner's own funding source.

Example request

curl "https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39/ads/ad-accounts?healthy=true" \
  -H "Authorization: Bearer lp_..."

const res = await fetch(
  `https://api.layers.com/v1/projects/${projectId}/ads/ad-accounts?healthy=true`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { items } = await res.json();

import httpx

r = httpx.get(
    f"https://api.layers.com/v1/projects/{project_id}/ads/ad-accounts",
    params={"healthy": True},
    headers={"Authorization": f"Bearer {api_key}"},
)
items = r.json()["items"]

Response

{
  "items": [
    {
      "adAccountId": "01HXF1A2B3C4D5E6F7G8H9J0K1",
      "platform": "meta_ads",
      "externalId": "act_123456789012345",
      "name": "Acme Coffee - US",
      "currency": "USD",
      "timezone": "UTC",
      "tokenStatus": "valid",
      "tokenLastValidatedAt": null,
      "connectedAt": "2026-03-02T14:11:00Z"
    },
    {
      "adAccountId": "01HXF2A2B3C4D5E6F7G8H9J0K1",
      "platform": "tiktok_ads",
      "externalId": "7389201...",
      "name": "Acme Coffee TikTok",
      "currency": "USD",
      "timezone": "UTC",
      "tokenStatus": "valid",
      "tokenLastValidatedAt": null,
      "connectedAt": "2026-03-18T09:42:00Z"
    },
    {
      "adAccountId": "01HXF3A2B3C4D5E6F7G8H9J0K1",
      "platform": "apple_ads",
      "externalId": "org-9823412",
      "name": "Acme Coffee iOS",
      "currency": "USD",
      "timezone": "UTC",
      "tokenStatus": "expired",
      "tokenLastValidatedAt": null,
      "connectedAt": "2026-02-11T19:05:00Z"
    }
  ]
}

All ad accounts are bring-your-own: the end-customer connects their own ad account via OAuth, and platform billing runs against the customer's own funding source on the platform.

Token status

tokenLastValidatedAt may be null until the first validation timestamp is available.

Notes

• Query the platform's own API if you need the account's spend or wallet state — Layers does not surface it.
• externalId is the platform-native account id - act_... on Meta, a numeric string on TikTok, org-... on Apple. Use it when linking out to the platform's ad manager.
• timezone may be "UTC" when the platform-native timezone is unavailable. If you need the local-clock timezone the ads are bidding against, query the platform's own API.
• A tokenStatus of expired or revoked does not immediately pause running ads - the platform keeps those running from its side. New ad creation against that ad account will fail until reconnected.
• Disconnected ad accounts are excluded from the response by default. There is no include-disconnected flag.

See also

• POST /v1/projects/:projectId/ads/ad-accounts/oauth-url - connect or reconnect
• GET /v1/projects/:projectId/ads/campaigns - campaigns on these accounts
• GET /v1/projects/:projectId/ads/capi-status - CAPI relay health per platform