---
title: "List board ads"
method: GET
path: "/open/v1/boards/{board_id}/ads"
tags: ["Boards"]
---

# List board ads

`GET /open/v1/boards/{board_id}/ads`

List the ads saved into a specific board. Filters here apply only to the ads in that board, not the global ad library.

Returns: `code=0` success; `code=40001` invalid `board_id` or workspace context missing; `code=40401` when the board is not accessible to the caller's workspace.

## Path parameters

- `board_id` string, required — Workspace-scoped board UUID. Obtain it from `GET /open/v1/boards`.

## Query parameters

- `query` string — Free-text search inside this board's ads.
- `platform` OpenAdPlatform[] — Filter by ad platform. Repeatable. Allowed values: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp`, `tiktok`, `linkedin`.
- `display_format` OpenAdDisplayFormat[] — Filter by display format. Repeatable. Allowed values: `image`, `video`, `carousel`, `multi_images`, `multi_videos`, `dco`, `dpa`.
- `language` string[] — Filter by ad copy language (ISO 639-1).
- `start_date` string — Inclusive lower bound on ad start date, format `YYYY-MM-DD`.
- `end_date` string — Inclusive upper bound on ad end date, format `YYYY-MM-DD`.
- `status` OpenAdStatus[] — Filter by ad status. Repeatable. Allowed values: `active`, `inactive`.
- `order` 'newest' | 'oldest' | 'most_active' — Subset of OpenAdsOrder: best_match is unsupported on board-scoped ads because ES rescore is incompatible with the nested _user_prefs filter used to scope by board.
- `page_size` integer — Items per page (1-50, default 20).
- `cursor` string — Opaque pagination cursor from the previous response.

## Response `200`

Successful Response

- OpenLibraryAdListResponse — Envelope for all open API responses. code=0 means success.
  - `code` integer
  - `message` string
  - `data` OpenLibraryAdListData — Cursor-based pagination wrapper (ads).
    - `items` OpenLibraryAd[]
      - `id` string, required — Atria-prefixed stable ad identifier. Format `m*` (Meta) or `t*` (TikTok). Use this value for path parameters on ad-detail and ad-script endpoints.
      - `platform_native_id` string — Raw platform-native ad id (Meta `ad_archive_id`, TikTok ad id). Useful only when cross-linking to external systems; not accepted on any Atria path parameter — use `id` for that.
      - `status` string — Ad lifecycle status: `active` (currently running) or `inactive` (stopped).
      - `brand_id` string — Atria-prefixed id of the advertising brand (matches `OpenLibraryBrand.id`).
      - `brand_name` string — Display name of the advertising brand.
      - `platforms` string[] — Platforms this ad ran on. Values from `OpenAdPlatform` (`facebook`, `instagram`, `tiktok`, ...).
      - `display_format` string — Creative format: `image`, `video`, `carousel` (multi-card swipe), or `dco` (dynamic creative; variants live in the merged `images` / `videos` arrays).
      - `title` string — Ad headline / title copy.
      - `body` string — Primary body copy.
      - `caption` string — Caption / link description shown beside the creative.
      - `cta_text` string — Call-to-action button label shown to users (e.g. `Shop now`, `Learn more`).
      - `link_url` string — Destination URL the ad sends clicks to (e.g. product page, landing page). Distinct from the Atria-side ad preview.
      - `images` OpenAdImage[] — Image media attached to the ad (carousel cards flatten in here too).
        - `url` string — Direct image URL.
        - `width` integer — Width in pixels.
        - `height` integer — Height in pixels.
      - `videos` OpenAdVideo[] — Video media attached to the ad.
        - `url` string — Direct video URL (HD preferred, SD fallback).
        - `preview_image_url` string — Thumbnail / poster frame extracted from the video.
        - `width` integer — Width in pixels.
        - `height` integer — Height in pixels.
        - `duration` number — Duration in seconds.
      - `start_date` string — First date the ad was observed running (ISO-8601 `YYYY-MM-DD`).
      - `end_date` string — Last date the ad was observed running (ISO-8601 `YYYY-MM-DD`). Null for ads still active.
    - `total` integer — Total number of matching ads. For brand-scoped queries this is exact. For broad/global queries the count is capped at 10000 — a value of 10000 should be read as `>= 10000`, not exactly 10000. Use `cursor` (not `total`) to determine end-of-results.
    - `cursor` string
    - `page_size` integer — Number of items actually returned on this page (== len(items)). On the last page or when the matching set is smaller than the requested page size, this is less than what the caller asked for.

## Other responses

- `400` — Invalid request — a query parameter, path parameter, or body field failed validation.

---

[API](https://skmtc.net/tryatria/apis/atria-open-api.md) · [All operations](https://skmtc.net/tryatria/apis/atria-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryatria/atria-open-api/revisions/548d57b611ea/schema)