> ## 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 Id > 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. ## OpenAPI ````yaml openapi/zh/foreplay.json GET /apis/v1/foreplay/brand/getAdsByBrandId openapi: 3.1.0 info: description: '' title: foreplay version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: - /apis/v1/foreplay/brand/analytics - /apis/v1/foreplay/brand/getAdsByBrandId - /apis/v1/foreplay/brand/getBrandsByDomain - /apis/v1/foreplay/discovery/ads x-aisa-document: facts_hash: 45ce32b5d2de49bb641c368c8d52e3cc198d5f8fd4d550b370b8c779bbf9f41e generator_version: '2' protocol_version: '1' schema_version: '1' composer_version: '13' response_pending: [] document_hash: sha256:127fa77e132696034d322cbb9cdac88d3512ed201b72998f687dde3a2766f106 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: foreplay x-aisa-catalogs: foreplay: title: foreplay description: '' x-aisa-document: facts_hash: 45ce32b5d2de49bb641c368c8d52e3cc198d5f8fd4d550b370b8c779bbf9f41e generator_version: '2' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/foreplay/brand/getAdsByBrandId: get: tags: - foreplay summary: Get Ads By Brand Id 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: 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' - 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: video_duration_min in: query required: false description: >- Filter ads by minimum video duration in seconds. Only applies to video ads. schema: type: string 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 default: content: application/json: schema: {} description: >- Error response; upstream passthrough responses may use provider formats components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.