---
title: "Retrieve Display Ads"
method: GET
path: "/v2/display-ads"
tags: ["Display Ads"]
---

# Retrieve Display Ads

`GET /v2/display-ads`

Retrieves ads for each of the given placements. Each placement maps to a typed response object. Banner placements return a single flattened ad; multi-banner placements return an array of ads ordered by auction rank. If no ad is available for a placement, the placement will be missing from the response. Placements are specified as repeated `placements` query parameters. Optionally, `num_results[{id}]=N` can be used to request a specific number of ads for a placement. When omitted, the placement's configured maximum is used.

## Query parameters

- `key` string, required — The key of the index to use.
- `query` string, nullable — Search query for keyword targeting.
- `filter_name` string, nullable — The name of the related browse filter.
- `filter_value` string, nullable — The value of the related browse filter.
- `num_results` object
- `placements` string[], required — Placement customer IDs to fetch ads for.

## Response `200`

Successful Response.

- DisplayAdsV2Response
  - `display_ads` object, required — Map of placement IDs to placement response objects. Banner placements return a single flattened ad object with type 'image_banner'. Multi-banner placements return an object with type 'multi' and an 'ads' array. If a placement ID is missing it means that there are no available ads for that placement.

## Other responses

- `400` — Bad Request.

---

[API](https://skmtc.dev/constructor/apis/autocomplete.md) · [All operations](https://skmtc.dev/constructor/apis/autocomplete/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/constructor/autocomplete/revisions/2d33330633b6/schema)