> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Ads by Brand IDs > Retrieve ads for one or more Foreplay brand IDs, applying the supplied filters; each result is a full ad object. Retrieve ads for one or more known Foreplay brand IDs (`brand_ids`, comma-separated), applying the same rich filter set as discovery (live status, display format, publisher platform, niche, market target, language, video/running duration, date range, order). Each result in `data[]` is a full ad object. Use `cursor` + `limit` (max 250) to page. ⚠️ **Accepts `brand_ids` only.** `page_id` lookup is **NOT supported** on the AIsa gateway — resolve a domain to its `ad_library_id` / brand id via [`get_foreplay-getbrandsbydomain`](/docs/api-reference/foreplay/get_foreplay-getbrandsbydomain) first. Passing a page id in `brand_ids` returns **HTTP 200 with `count: 0`** (silently treated as an unknown brand). This is intentional P0 scoping, documented as a known limitation. `display_format` accepts exactly these 11 values: `carousel`, `dco`, `dpa`, `event`, `image`, `multi_images`, `multi_medias`, `multi_videos`, `page_like`, `text`, `video`. \*\*Billing: $0.02625 per item returned in `data[]`; empty results and errors are not charged.** One credit per ad; a call with `limit≤50` costs at most $1.3125. Example: `GET /foreplay/brand/getAdsByBrandId?brand_ids=bYeKOahyGopmGKMHiWit` (Nike, resolved via `getBrandsByDomain?domain=nike.com`). Related: [`get_foreplay-getbrandsbydomain`](/docs/api-reference/foreplay/get_foreplay-getbrandsbydomain) (resolve `brand_ids` from a domain), [`get_foreplay-discovery-ads`](/docs/api-reference/foreplay/get_foreplay-discovery-ads), [`get_foreplay-brand-analytics`](/docs/api-reference/foreplay/get_foreplay-brand-analytics). ## OpenAPI ````yaml openapi/foreplay.json GET /foreplay/brand/getAdsByBrandId openapi: 3.0.3 info: title: Foreplay API version: 1.0.0 description: >- Foreplay ad creative intelligence routed through the AIsa gateway. Search a 100M+ ad library, pull ads for known brands, resolve brands by domain, and get brand-level running-ads distribution and creative velocity analytics. All data endpoints are billed per item returned in `data[]` ($0.02625 / item); empty results and 4xx/5xx errors are not charged. servers: - url: https://api.aisa.one/apis/v1 security: - BearerAuth: [] paths: /foreplay/brand/getAdsByBrandId: get: summary: Get Ads by Brand IDs description: >- Retrieve ads for one or more Foreplay brand IDs, applying the supplied filters. Each result in `data[]` is a full ad object. **Accepts `brand_ids` only.** `page_id` lookup is NOT supported on the AIsa gateway — resolve a domain to its `ad_library_id` / brand id via `getBrandsByDomain` first. Passing a page id in `brand_ids` returns HTTP 200 with `count: 0` (silently treated as an unknown brand). This is intentional P0 scoping, documented as a known limitation. Billed $0.02625 per item returned in `data[]` (1 credit per item); empty results and 4xx/5xx errors are not charged. operationId: get_ads_by_brand_ids parameters: - name: brand_ids in: query required: true description: >- Brand ID(s) to search for. Can be a single ID or multiple IDs separated by commas. schema: type: array - name: live in: query required: false description: >- Filter ads by live status. `true` means currently active ads, `false` means inactive ads. Leave empty to include both. schema: type: string - name: display_format in: query required: false description: >+ Filter by one or more display formats. Available formats (11): carousel, dco, dpa, event, image, multi_images, multi_medias, multi_videos, page_like, text, video Example: `?display_format=video&display_format=carousel` schema: type: string enum: - carousel - dco - dpa - event - image - multi_images - multi_medias - multi_videos - page_like - text - video - name: publisher_platform in: query required: false description: >+ Filter by one or more publisher platforms. Available platforms: facebook, instagram, audience_network, messenger, tiktok, youtube, linkedin, threads, whatsapp Example: `?publisher_platform=facebook&publisher_platform=instagram` schema: type: string enum: - facebook - instagram - audience_network - messenger - tiktok - youtube - linkedin - threads - whatsapp - name: niches in: query required: false description: >+ Filter by one or more niches. Available niches: travel, food, fashion, beauty, health, technology, automotive, finance, education, entertainment, sports, home, pets, business, other Example: `?niches=travel&niches=fashion` schema: type: string - name: market_target in: query required: false description: >+ Filter by market target. Available targets: b2b (business-to-business), b2c (business-to-consumer) Example: `?market_target=b2b` schema: type: string - name: languages in: query required: false description: >+ Filter by languages. Accepts various language formats: 'french', 'FR', 'romanian', 'ro', 'english', 'en', etc. Example: `?languages=en&languages=fr` schema: type: string - name: video_duration_min in: query required: false description: >- Filter ads by minimum video duration in seconds. Only applies to video ads. schema: type: string - name: video_duration_max in: query required: false description: >- Filter ads by maximum video duration in seconds. Only applies to video ads. schema: type: string - name: running_duration_min_days in: query required: false description: >- Filter ads by minimum running duration in days. Must be a positive integer. schema: type: string - name: running_duration_max_days in: query required: false description: >- Filter ads by maximum running duration in days. Must be a positive integer. schema: type: string - name: start_date in: query required: false description: >- Start date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To get all ads from a specific day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. schema: type: string - name: end_date in: query required: false description: >- End date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS', or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g. '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To include all results for a given day, set end_date to 'YYYY-MM-DD 23:59:59' or to the next day at '00:00:00'. Examples: start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. schema: type: string - name: order in: query required: false description: >- Order of results: 'newest' (default), 'oldest', 'longest_running', or 'most_relevant'. Sorts ads by creation date, longest running duration, or relevance to the search query. schema: type: string default: newest enum: - newest - oldest - longest_running - most_relevant - name: cursor in: query required: false description: >- Cursor for pagination. Use the cursor value from the previous response's metadata to get the next page of results. schema: type: string - name: limit in: query required: false description: >- Pagination limit (max 250). Controls the number of ads returned per request. schema: type: integer default: 10 maximum: 250 - name: collect in: query required: false description: >- Best-effort live fallback. If the cached results are empty and `collect=true`, the API translates each brand id to its Meta page id (`adlibraryid`), kicks off a live fetch through our Spyder pipeline, and polls for ~30 seconds. Returns whatever is available at the end of the window — may still be empty if a brand has no Meta page on file, the page is restricted, deleted, or simply isn't running ads. Not perfect — use it as a fallback when the regular response is empty, not as a default. schema: type: string default: false responses: '200': description: >- JSON envelope with `metadata` and a `data[]` array of ad objects. Each ad in `data[]` counts as one billed item. content: application/json: schema: type: object example: metadata: success: true status_code: 200 count: 1 cursor: null data: - id: abc123 brand_id: bYeKOahyGopmGKMHiWit brand_name: Nike display_format: video publisher_platform: facebook live: true error: null components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: AISA API Key ````