---
title: "List banners"
type: reference
method: GET
path: /rest-api/banners.do
tag: "Banners"
---

# List banners

`GET https://YOUR-NETWORK-DOMAIN/rest-api/banners.do`

Returns a paginated list of banners accessible to the authenticated user. Results can be filtered by campaign, advertising categories, template IDs, approval statuses, labels, banner name, active state, placement type, creative type and any on/off setting (filter[...]); every filter narrows the result, and a list filter matches any of its values. fields trims each banner to the fields named. A labels filter naming no existing label returns an empty list. Each banner in the response includes traffic status, linkage state, and native preferences (for native banners). Use the selfServRequest flag to receive the Self-Serve response format.

## Query params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `advertisingCategories` | array<integer> | no | `5` | IDs of advertising categories to filter by |
| `templateIds` | array<integer> | no | `100` | Template IDs to filter by |
| `approvalStatuses` | array<string> | no | `APPROVED` | Approval statuses to filter by (e.g., NEW, PENDING, APPROVED, REJECTED) |
| `labels` | array<string> | no | `premium` | Label names to filter by |
| `campaignId` | integer | no | `2001` | Campaign ID to restrict results to a single campaign |
| `offset` | integer | no | `0` | Pagination offset (0-based) |
| `limit` | integer | no | `25` | Maximum number of banners to return |
| `selfServRequest` | boolean | no | `false` | If true, returns the Self-Serve response format |
| `bannerName` | string | no | `summer` | Part of the banner name to search for, case-insensitive |
| `active` | boolean | no | `true` | When set, returns only active (true) or only inactive (false) banners; omit to return both |
| `placementTypes` | array<string> | no | `VIDEO_PLACEMENT` | Placement types the banners are made for, e.g. VIDEO_PLACEMENT; a banner matching any of them is returned |
| `bannerTypes` | array<string> | no | `TEMPLATE` | Creative types to filter by, e.g. VAST_2_0_TAG_URL; a banner matching any of them is returned |
| `fields` | array<string> | no | `id,name,active` | Return only these fields of each entity, comma-separated; id is always kept. A requested field no returned row carries is named in the X-Ignored-Fields response header |
| `filter` | object | no | `{"hasLimits": "true"}` | Keep only entities matching every key, e.g. filter[cpaOptimization]=true&filter[hasLimit]=true. Keys are the entity's on/off settings (active, enableTargeting, cpaOptimization, alwaysRedirect, ...) and a has<Relation> flag for each setting kept in rows of its own (hasLimit, hasPricing, hasFrequencyCapping, hasTrackingCode, hasPriceAdjustmentRules, hasLabels, hasBanners, ...), true when the relation holds a row; hasCapping, hasLimits and hasTargetingRules group the relations of their kind. An unknown key is a 400 that lists every valid key for the list. |

## Responses

- `200` — List of banners
- `400` — Bad request — invalid or missing parameters
- `401` — Authentication error
- `403` — Forbidden — insufficient permissions

## Example request

```bash
curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/banners.do?campaignId=2001&active=true&advertisingCategories=5&templateIds=100' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

Source: https://epom.com/ad-server/docs/api/banners/get-banners