GET /v1/projects/:projectId/ads/adsets

GET/v1/projects/{projectId}/ads/adsets

Phase 1stable

Auth: Bearer
Scope: ads:read

Lists every ad set under the project's connected ad accounts, across platforms. TikTok and Apple call these "ad groups"; Layers normalizes them to "adsets" so you can render one shape without per-platform branches. Each item carries its parent campaign, current status, optimization goal, targeting summary, and budget.

Adset writes (PATCH …/adsets/:id/budget, …/adsets/:id/targeting, …/adsets/:id/schedule, plus …/{pause,resume}, DELETE) are partner-callable with ads:write:budgets / :lifecycle / :creative. All writes route through the bucket-mode authority gate.

Path

projectId
string (UUID)required
Project to list within.

Query

campaignId
string (UUID)optional
Restrict to ad sets on one campaign.
platforms
string[]optional
Restrict to one or more platforms.
One of: meta_ads, tiktok_ads, apple_ads
adAccountId
string (UUID)optional
Restrict to ad sets on one ad account.
status
string[]optional
Filter by platform-native status.
One of: active, paused, archived, deleted, in_review, rejected
cursor
stringoptional
Opaque pagination cursor. Forged or malformed cursors are rejected and treated as no cursor (first page).
limit
numberoptionaldefault: 100
Page size, 1–200.

Example request

curl "https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39/ads/adsets?campaignId=cmp_01HXG9&status=active" \
  -H "Authorization: Bearer lp_..."

const res = await fetch(
  `https://api.layers.com/v1/projects/${projectId}/ads/adsets?campaignId=${campaignId}&status=active`,
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
const { items, nextCursor } = await res.json();

import httpx

r = httpx.get(
    f"https://api.layers.com/v1/projects/{project_id}/ads/adsets",
    params={"campaignId": campaign_id, "status": "active"},
    headers={"Authorization": f"Bearer {api_key}"},
)
items = r.json()["items"]

Response

200OK

{
  "items": [
    {
      "adsetId": "adg_01HXG9...",
      "campaignId": "cmp_01HXG9...",
      "adAccountId": "aa_01HXF1...",
      "platform": "meta_ads",
      "externalId": "23852014...",
      "name": "Q2 Mobile Ordering - Prospecting - Lookalike 1%",
      "status": "active",
      "optimizationGoal": "offsite_conversions",
      "billingEvent": "impressions",
      "dailyBudget": { "amount": 75.00, "currency": "USD" },
      "lifetimeBudget": null,
      "startTime": "2026-04-01T00:00:00Z",
      "endTime": null,
      "targetingSummary": {
        "geo": ["US"],
        "age": { "min": 25, "max": 45 },
        "customAudiences": ["aud_lookalike_1pct_purchasers"],
        "placements": ["facebook_feed", "instagram_feed", "instagram_reels"]
      },
      "createdAt": "2026-03-29T15:04:00Z",
      "metricsSnapshot7d": {}
    },
    {
      "adsetId": "adg_01HXGB...",
      "campaignId": "cmp_01HXGB...",
      "adAccountId": "aa_01HXF2...",
      "platform": "tiktok_ads",
      "externalId": "1785502...",
      "name": "Q2 Retargeting - 30d Site Visitors",
      "status": "paused",
      "optimizationGoal": "conversion",
      "billingEvent": "oCPM",
      "dailyBudget": null,
      "lifetimeBudget": { "amount": 1500.00, "currency": "USD" },
      "startTime": "2026-04-10T00:00:00Z",
      "endTime": "2026-05-10T00:00:00Z",
      "targetingSummary": {
        "geo": ["US"],
        "age": { "min": 18, "max": 54 },
        "customAudiences": ["aud_site_visitors_30d"],
        "placements": ["tiktok_feed"]
      },
      "createdAt": "2026-04-08T21:18:00Z",
      "metricsSnapshot7d": {}
    }
  ],
  "nextCursor": null
}

Notes

optimizationGoal and billingEvent are platform-native strings. Meta and TikTok use different vocabularies; do not assume conversion on TikTok means the same thing as offsite_conversions on Meta.
targetingSummary is a summary, not the full targeting spec. Platforms encode targeting in very different JSON shapes; Layers surfaces the pieces almost every agent cares about (geo, age, custom audiences, placements) and skips the rest. For the raw spec, fall through to the platform's own API.
metricsSnapshot7d is reserved for a future inline rollup. It is always {} today; call GET /v1/projects/:projectId/ads-metrics with scope=adset and an explicit window for paid performance.
endTime of null means the ad set runs indefinitely (on platforms that allow it). TikTok lifetime-budget adsets always have an endTime.
Soft-deleted ad sets are included by default. Filter them out with status if you only want live work.

GET /v1/projects/:projectId/ads/adsets

Example request

Response

Notes

See also

On this page