---
title: "List saved library ads"
method: GET
path: "/open/v1/ad-library/saved"
tags: ["Ad Library"]
---

# List saved library ads

`GET /open/v1/ad-library/saved`

List ads the calling workspace has saved from the global ad library. Each item carries the standard ad fields plus a `saved_details` block (`saved_at`, `boards`, `tags`).

Scoped to the workspace bound to your API key. Use the response `cursor` to paginate.

Returns: `code=0` success; `code=40001` invalid query parameters.

## Query parameters

- `query` string — Free-text search against ad title, body and brand name.
- `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`.
- `boards` string[] — Restrict to ads saved in the given board(s). Pass `board_id` values from `GET /open/v1/boards`. Repeatable.
- `tags` string[] — Restrict to ads tagged with any of the given tag names.
- `order` 'saved_newest' | 'saved_oldest' | 'newest' | 'oldest' | 'most_active' — An enumeration.
- `page_size` integer — Items per page (1-50, default 20).
- `cursor` string — Opaque pagination cursor from the previous response.

## Response `200`

Successful Response

- OpenSavedAdListResponse — Envelope for all open API responses. code=0 means success.
  - `code` integer
  - `message` string
  - `data` OpenSavedAdListData — Cursor-based pagination wrapper (ads).
    - `items` OpenSavedAd[]
      - `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.
      - `saved_details` OpenSavedDetails
        - `saved_at` string — When the ad was saved to this workspace (ISO-8601 UTC timestamp).
        - `boards` string[] — Board ids the ad is pinned under in this workspace. Empty if the ad was saved without board assignment.
        - `tags` string[] — User-applied tags on the saved ad. Workspace-specific.
    - `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)