---
title: "Read an ad account's campaigns and ad sets live"
method: GET
path: "/v1/ads/accounts/live"
tags: ["Ad Accounts"]
---

# Read an ad account's campaigns and ad sets live

`GET /v1/ads/accounts/live`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/ads/accounts/live`
- Auth: HTTP bearer

Reads an ad account's campaigns and ad sets straight from Meta or TikTok, so checks like budget limits see current values.

Reads the campaigns and ad sets of one Meta ad account or TikTok advertiser **live from
the platform**, so it is cheap enough to run before every write: for example a
per-ad-account spend ceiling that must see the current daily / lifetime budget rather
than the synced copy. On Meta it is a single Graph call per request (the account's
`/campaigns` and `/adsets` edges, filtered by `effective_status`); on TikTok one
`campaign/get` and one `adgroup/get` page (TikTok ad groups are returned as `adSets`).

**Live vs synced.** GET /v1/ads/campaigns and GET /v1/ads/ad-sets serve Zernio's synced
store, refreshed by background sync (typically 15 to 60 minutes behind Meta), and their
`live=true` re-reads only the on/off switches of at most 20 objects. This endpoint returns
what Meta reports at `readAt`, for every matching campaign and ad set, and stores nothing.

Budgets and bid amounts are in whole units of `currency`, the same units as the synced
rows (Meta's minor units are converted; TikTok already reports whole units). A campaign
with a campaign budget (Meta Advantage+ campaign budget, TikTok campaign budget
optimization) carries `budget`; otherwise each ad set carries its own.

Each level returns at most `limit` rows. When more match, `paging.<level>.after` is a
cursor: pass it back as `after` together with `level` to read the next page of that
level only. TikTok pages by number, so a TikTok cursor must be sent with the same
`limit` that produced it (another `limit` is a 400). Other platforms answer 501 rather
than serving synced data.

**TikTok specifics.** `status` maps to TikTok's `primary_status` filter, which takes one
value: ACTIVE = delivering (`STATUS_DELIVERY_OK`), PAUSED = switched off
(`STATUS_DISABLE`), DELETED = `STATUS_DELETE`; omitted = every status except deleted
(`STATUS_NOT_DELETE`, which includes enabled entities that are not delivering, such as
an ad group in review). Several values, or IN_PROCESS, WITH_ISSUES, CAMPAIGN_PAUSED and
ARCHIVED, are a 400. `budgetRemaining` and `spendCap` are always null (TikTok reports
neither), campaign `bidStrategy` is null (TikTok bids per ad group), ad set `bidStrategy`
is normalized to the Meta vocabulary like GET /v1/ads, `promotedObject` is
`{ pixelId, customEventType, applicationId, customConversionId }` (the keys TikTok has
set, as POST /v1/ads/create takes them), and `targeting` holds TikTok's targeting
fields verbatim.

## Query parameters

- `accountId` string, required
- `adAccountId` string, required
- `status` string
- `level` 'campaign' | 'adSet'
- `limit` integer
- `after` string

## Response `200`

Live campaigns and ad sets

- object
  - `accountId` string
  - `adAccountId` string
  - `platform` 'facebook' | 'tiktok'
  - `currency` string: ISO 4217 code every budget and bid amount is expressed in.
  - `readAt` string, date-time: When the platform was read.
  - `campaigns` object[]: Absent when `level=adSet`.
    - `platformCampaignId` string
    - `campaignName` string, nullable
    - `platformCampaignStatus` string, nullable: Meta `effective_status` (ACTIVE, PAUSED, WITH_ISSUES...) or TikTok `secondary_status` (CAMPAIGN_STATUS_ENABLE...).
    - `configuredStatus` string, nullable: The campaign's own switch: Meta `status` (ACTIVE, PAUSED, DELETED, ARCHIVED), or TikTok `operation_status` as ACTIVE (ENABLE) / PAUSED (DISABLE).
    - `status` string: Zernio's normalized status (active, paused, ...), derived from `platformCampaignStatus`.
    - `budget` object, nullable: The campaign budget, same shape as the synced rows. Null when the budget lives on the ad sets.
      - `amount` number
      - `type` 'daily' | 'lifetime'
    - `dailyBudget` number, nullable: Daily budget in whole units of `currency` (Meta `daily_budget`; TikTok `budget` under a daily budget mode).
    - `lifetimeBudget` number, nullable: Lifetime budget in whole units of `currency` (Meta `lifetime_budget`; TikTok `budget` under BUDGET_MODE_TOTAL).
    - `budgetMode` string, nullable: TikTok only: `budget_mode` as TikTok reports it (BUDGET_MODE_DAY, BUDGET_MODE_DYNAMIC_DAILY_BUDGET, BUDGET_MODE_TOTAL, BUDGET_MODE_INFINITE).
    - `budgetRemaining` number, nullable: Meta `budget_remaining` in whole units of `currency`. Null when the campaign has no budget of its own, and always on TikTok.
    - `spendCap` number, nullable: Campaign spending limit (Meta `spend_cap`) in whole units of `currency`. Null when none is set, and always on TikTok.
    - `bidStrategy` string, nullable: Meta `bid_strategy`, set on campaigns with a campaign budget. Null on TikTok.
  - `adSets` object[]: Absent when `level=campaign`.
    - `platformAdSetId` string
    - `adSetName` string, nullable
    - `platformCampaignId` string, nullable
    - `platformAdSetStatus` string, nullable: Meta `effective_status` (ACTIVE, PAUSED, CAMPAIGN_PAUSED...) or TikTok `secondary_status` (ADGROUP_STATUS_DELIVERY_OK, ADGROUP_STATUS_AUDIT...).
    - `configuredStatus` string, nullable: The ad set's own switch: Meta `status`, or TikTok `operation_status` as ACTIVE / PAUSED.
    - `status` string: Zernio's normalized status, derived from `platformAdSetStatus`.
    - `budget` object, nullable: The ad set budget, same shape as the synced rows. Null under a campaign budget.
      - `amount` number
      - `type` 'daily' | 'lifetime'
    - `dailyBudget` number, nullable: Daily budget in whole units of `currency`.
    - `lifetimeBudget` number, nullable: Lifetime budget in whole units of `currency`.
    - `budgetMode` string, nullable: TikTok only: `budget_mode` as TikTok reports it.
    - `budgetRemaining` number, nullable: Meta `budget_remaining` in whole units of `currency`. Null when the ad set has no budget of its own, and always on TikTok.
    - `bidStrategy` string, nullable: Meta `bid_strategy`. On TikTok the ad group's `bid_type` normalized to the same vocabulary (LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS).
    - `bidAmount` number, nullable: Bid cap or cost target in whole units of `currency` (Meta `bid_amount`; TikTok `bid_price`, else `conversion_bid_price`, else `deep_cpa_bid`). Null when the strategy has none.
    - `optimizationGoal` string, nullable: Meta or TikTok `optimization_goal`.
    - `billingEvent` string, nullable: Meta or TikTok `billing_event`.
    - `promotedObject` object, nullable: Meta `promoted_object` verbatim (snake_case). On TikTok `{ pixelId, customEventType, applicationId, customConversionId }` from `pixel_id`, `optimization_event`, `app_id` and `custom_conversion_id`, only the keys TikTok has set; null when none is.
    - `targeting` object, nullable: The platform's targeting verbatim (snake_case), as it reports it now: Meta `targeting`, or TikTok's ad group targeting fields (location_ids, age_groups, gender, languages, interest_category_ids, audience_ids, placements...).
    - `schedule` object, nullable
      - `startDate` string, date-time
      - `endDate` string, date-time: Absent when the ad set runs until it is stopped.
  - `paging` object: One entry per level read. `after` is null on the last page.
    - `campaigns` object
      - `after` string, nullable
    - `adSets` object
      - `after` string, nullable

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: Ads access required (Ads add-on on legacy plans, included on usage-based plans).
- `404`: The account or requested resource was not found or is not accessible. An account ID may have been disconnected and removed. Read GET /v1/accounts for current account IDs.
- `409`: The account exists but is inactive or needs reconnection. Reconnect it, then read GET /v1/accounts for its current account ID before retrying. Code: ads_connection_required.
- `429`: Platform rate limit reached; retry later (after the indicated delay on Meta).
- `501`: The platform has no bulk live read (Meta and TikTok today). Use the synced GET /v1/ads/campaigns and GET /v1/ads/ad-sets there.
- `502`: The platform did not return the ad account or its currency (for example a deleted ad account).

## Changes

- **2026-10-07** `664b218652be`: 1 warning, 2 info
  - added the new `tiktok` enum value to the `platform` response property for the response status `200`
  - added the optional property `adSets/items/budgetMode` to the response with the `200` status
  - added the optional property `campaigns/items/budgetMode` to the response with the `200` status
- **2026-10-06** `f8c8f34fb41a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/accounts/live/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/4e74db179e73?raw)