> ## 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.

# List advertisers

> Page through advertiser summaries with filtering

`GET /api/v2/buyer/advertisers`

Returns a paginated list of advertiser summary rows. Each row is the compact shape — call [Get advertiser](/v2/buyer/advertisers/tasks/get-advertiser) for the full resource with brand, linked accounts, UTM config, and frequency caps.

This endpoint normally requires a Buyer Account. A Seller Account in
the [Media Company V3 preview](/v2/features/sandbox#media-company-v3-preview)
may use this list endpoint to populate its native Campaigns workspace. For that
Seller-only compatibility read, an omitted `sandbox` parameter or `sandbox=true`
returns only sandbox Advertisers with an active organization-owned binding to
that Seller Account's Storefront — available to every Seller Account, no
rollout enrollment required. `sandbox=false` returns the same Seller Account's
live own-supply Advertisers instead, and requires the account to be enrolled
in the `amc-campaign-management` rollout; an unenrolled Seller Account gets
`403 OWN_SUPPLY_SCOPE_REQUIRED` for that request. Unbound Advertisers in
either environment are not part of this roster. The Campaigns workspace also
uses two narrowly scoped compatibility reads: [List campaigns](/v2/buyer/campaigns/tasks/list-campaigns)
for a bound Advertiser and that Advertiser's promoted Creative list.
Advertiser detail, Campaign and Creative detail, mutations, and reporting
remain unavailable through Buyer REST to the Seller Account.

## Request

```bash curl theme={null}
curl "https://api.apostra.com/api/v2/buyer/advertisers?search=acme&limit=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

## Parameters

| Field                    | Type    | Required | Notes                                                                                                     |
| ------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `status`                 | enum    | No       | `ACTIVE`, `ARCHIVED`, or `ALL`. Defaults to `ACTIVE`                                                      |
| `name`                   | string  | No       | Case-insensitive partial match on advertiser name                                                         |
| `search`                 | string  | No       | Case-insensitive partial match on advertiser name or ID. Exact ID matches appear first                    |
| `sandbox`                | boolean | No       | `true` returns only sandbox advertisers, `false` only production. Omit for all                            |
| `linkedAccountPartnerId` | string  | No       | Exact partner / sales-agent ID. Returns only advertisers with a currently linked account for that partner |
| `limit`                  | integer | No       | Max rows per page. Default `100`, max `100`                                                               |
| `offset`                 | integer | No       | Rows to skip for pagination. Default `0`                                                                  |

`search` is applied to the full authorized roster before `limit` and `offset`,
so matching advertisers remain discoverable beyond the first page. Use `name`
when only advertiser names should match.

## Response

```json theme={null}
{
  "items": [
    {
      "id": "12345",
      "name": "Acme Corp",
      "status": "ACTIVE",
      "sandbox": false,
      "brand": "acme.com",
      "brandCountries": ["DE", "NL"],
      "primaryCurrency": "USD",
      "preferredTimezone": "Europe/Amsterdam",
      "reportingTimezoneLocked": false,
      "channels": ["display", "ctv"],
      "currencyLocked": false,
      "linkedAccountCount": 3,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "total": 42,
  "hasMore": false,
  "nextOffset": null
}
```

Summary rows also carry `brandCountries`, `primaryCurrency`,
`preferredTimezone`, `reportingTimezoneLocked`, `channels`, and
`currencyLocked`, so account setup can render without fetching every full
advertiser. Market and channel values are advertiser planning inputs; seller
selection remains account-wide. `linkedAccountCount` replaces the embedded
account list. When `hasMore` is `true`, pass `nextOffset` as the next `offset`.

## Errors

* `400 VALIDATION_ERROR` — invalid `status` value or out-of-range `limit`.
* `403 CUSTOMER_ROLE_DENIED` — the account is neither a Buyer Account nor a
  Seller Account using this advertiser roster.
* `403 OWN_SUPPLY_SCOPE_REQUIRED` — the Seller Account has no active
  Storefront scope for the requested environment's roster, or requested
  `sandbox=false` without `amc-campaign-management` enrollment.

The Seller sandbox roster is available by account role; it does not require a
separate entitlement or rollout enrollment. The Seller live roster additionally
requires `amc-campaign-management` enrollment. All mutations remain outside
this compatibility read.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Advertiser tasks" href="/v2/buyer/advertisers/tasks" icon="list-check">
    All advertiser operations
  </Card>

  <Card title="Advertiser overview" href="/v2/object-guides/advertiser" icon="user-tie">
    Fields, lifecycle, and concepts
  </Card>

  <Card title="List organization advertisers" href="/v2/buyer/advertisers/tasks/list-organization-advertisers" icon="building-user">
    Read the authorized account-spanning roster
  </Card>

  <Card title="Get advertiser" href="/v2/buyer/advertisers/tasks/get-advertiser" icon="magnifying-glass">
    Fetch the full resource
  </Card>

  <Card title="Create advertiser" href="/v2/buyer/advertisers/tasks/create-advertiser" icon="plus">
    Open a new advertiser
  </Card>
</CardGroup>