> ## 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. # Search & Filter Ads > Search the Foreplay ad index (100M+ ads) with a text query plus filters; each result is a full ad object. Search across the Foreplay ad index with a text `query` plus filters (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 — image/video URLs, transcription, brand metadata, targeting, and more. Use `cursor` + `limit` (max 250) to page. `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. Related: [`get_foreplay-getadsbybrandid`](/docs/api-reference/foreplay/get_foreplay-getadsbybrandid), [`get_foreplay-getbrandsbydomain`](/docs/api-reference/foreplay/get_foreplay-getbrandsbydomain), [`get_foreplay-brand-analytics`](/docs/api-reference/foreplay/get_foreplay-brand-analytics). ## OpenAPI ````yaml openapi/foreplay.json GET /foreplay/discovery/ads 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/discovery/ads: get: summary: Search & Filter Ads description: >- Search across the Foreplay ad index (100M+ ads) with a text query plus filters. Each result in `data[]` is a full ad object (image/video URLs, transcription, brand metadata, targeting, and more). Billed $0.02625 per item returned in `data[]` (1 credit per item); empty results and 4xx/5xx errors are not charged. operationId: search_discovery_ads parameters: - name: query in: query required: false description: >- Search text for ad name or description. Leave empty to search all ads with filters only. 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: 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: accessories, app/software, beauty, business/professional, education, entertainment, fashion, food/drink, health/wellness, home/garden, jewelry/watches, other, parenting, pets, real estate, service business, medical, charity/nfp, kids/baby 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: 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: 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 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 ````