# Foreplay

> Competitor ad intelligence - search 200M+ Meta, TikTok and YouTube ads, brand analytics, tracked competitors, swipe file.

Competitor advertising research through the [Foreplay](https://www.foreplay.co)
Public API: search the ad library, pull every ad a brand runs, read brand
analytics and media mix, watch tracked competitors for new launches, and browse
your own swipe file and boards. Read-only.

## What it can do

| Method | What it does |
| --- | --- |
| `foreplay_search_ads` | Keyword search across the ad library with filters: date window, live only, format, platform, niche, b2b/b2c, language, video length, running duration; order by newest, longest running or relevance. |
| `foreplay_search_brands` | Find brands by name with their Foreplay brand ids and page ids. |
| `foreplay_explore_brands` | Discover brands by the ads they run (niche, platform, format, language, date window). |
| `foreplay_brands_by_domain` | Brands behind a website domain. |
| `foreplay_brand_ads` | All ads of one or more brands by brand id. |
| `foreplay_page_ads` | All ads of a Facebook page id. |
| `foreplay_brand_analytics` | Running ads distribution, media mix and activity of a brand or page over a date window. |
| `foreplay_ad_details` | One ad in full: creative, transcript, hooks, copy, landing page, platforms, first / last seen. |
| `foreplay_ad_duplicates` | Ads reusing the same image or video. |
| `foreplay_swipefile_ads` | Ads saved in your swipe file. |
| `foreplay_boards` / `foreplay_board_ads` | Your boards and the ads on them. |
| `foreplay_spyder_brands` / `foreplay_spyder_brand_ads` / `foreplay_spyder_top_ads` | Tracked competitors, their ads and top-ranked creatives with rank movement. |
| `foreplay_usage` | API usage and remaining quota. |

Lists paginate with `next_cursor`.

## How to get credentials

1. Sign in at [app.foreplay.co](https://app.foreplay.co) on a plan that includes
   API access.
2. Open **Settings → API** and create an API key.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `FOREPLAY_API_KEY` | Foreplay → Settings → API |

## Troubleshooting

- **HTTP 401** - the key was rejected; create a new one in Foreplay.
- **HTTP 402 / 403** - API access or that endpoint is not in your plan.
- **HTTP 429** - rate limit; check `foreplay_usage` and retry after a pause.
- **Empty brand results** - try `collect=true` on `foreplay_brand_ads` /
  `foreplay_page_ads` to let Foreplay fetch live from Meta.

## Links

- [Foreplay Public API docs](https://docs.foreplay.co/)
- [Foreplay API overview](https://www.foreplay.co/api)