<callout-component color="Accent">ℹ️ You are currently on the platform knowledge base.For full technical documentation go here 👉 <a target="" rel="noopener noreferrer nofollow" class="link" href="https://docs.foreplay.co/#description/step-1-get-your-api-key">API Technical Docs 🔗 </a> To chat with the the API technical docs 👉 <a target="" rel="noopener noreferrer nofollow" class="link" href="https://chatgpt.com/g/g-68b06c9529548191b5d25556e66a272a-foreplay-data-api-docs">Foreplay API GPT 🔗</a></callout-component>How to get your API keyThe Foreplay API is available across all plan types (excluding legacy plans). If you are having trouble accessing your API key or have questions about credits, check out <a target="_blank" rel="noreferrer" class="relative pb-0 pl-6 mb-0 mention-badge link" href="https://help.foreplay.co/en/articles/9082255-credits-and-pricing" data-organization-id="679b974052237795bccaf76f" data-help-center-id="1drjxqngeoezh4dp" data-slug="9082255-credits-and-pricing" data-article-id="9082255" data-locale="en" data-hash="">Credits &amp; Pricing</a>⚠️ Treat your API key like a password, don’t share it publicly or paste it into forums.<video data-width="100%" data-align="left" data-featurebase-content-key="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvYmplY3RLZXkiOiIwMTk5MTIwMC0yMDFhLTdjZTktOWFiMS1hMzQxYWQ2Njk0NmYiLCJ0eXBlIjoidmlkZW8tdXJsIiwicmVzb3VyY2VJZCI6IjY4YjhkM2RjMjE5ZjJmNjFlOTFlYzJlNyIsInJlc291cmNlVHlwZSI6ImFydGljbGUiLCJvcmdJZCI6IjY3OWI5NzQwNTIyMzc3OTViY2NhZjc2ZiIsImlhdCI6MTc1Njk0MzYyM30.KDk9f_-5nDA-Ib8j3jAup56ANLz-6p7pUUB9ePRiNdY" src="https://679b974052237795bccaf76f.featurebase-attachments.com/c/videos/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvYmplY3RLZXkiOiIwMTk5MTIwMC0yMDFhLTdjZTktOWFiMS1hMzQxYWQ2Njk0NmYiLCJleHAiOjE3NzI1MTA0MDAsInR5cGUiOiJ2aWRlby11cmwiLCJvcmdJZCI6IjY3OWI5NzQwNTIyMzc3OTViY2NhZjc2ZiIsInJlc291cmNlSWQiOiI2OGI4ZDNkYzIxOWYyZjYxZTkxZWMyZTciLCJyZXNvdXJjZVR5cGUiOiJhcnRpY2xlIn0.OALDx3Z-Yq122OQIpcT-9Bi1NK7Tv-X2Q-ezLDqxAI0/manifest.mpd"></video>To create your access key.<ol><li>Go to your API settings: <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://app.foreplay.co/api-overview">https://app.foreplay.co/api-overview</a></li><li>Click the copy icon</li></ol><h2 id="ip4l3rxdiz8" data-toc-id="ip4l3rxdiz8">Logs &amp; Troubleshooting</h2>As you are working with our API you can access logs directly from the API dashboard.Access Logs Here: <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://app.foreplay.co/api-logs">https://app.foreplay.co/api-logs</a><img data-width="100%" data-align="left" alt="" data-featurebase-content-key="679b974052237795bccaf76f/article/68b8d3dc219f2f61e91ec2e7/019911fc-2e89-7259-af74-961310138f9b/b64u-U2NyZWVuc2hvdCAyMDI1LTA5LTAzIGF0IDQuMjAuMznDosKAwq9QTS5wbmc.png" data-featurebase-content-filename="Screenshot 2025-09-03 at 4.20.39â¯PM.png" src="https://679b974052237795bccaf76f.featurebase-attachments.com/c/article/68b8d3dc219f2f61e91ec2e7/019911fc-2e89-7259-af74-961310138f9b/b64u-U2NyZWVuc2hvdCAyMDI1LTA5LTAzIGF0IDQuMjAuMznDosKAwq9QTS5wbmc.png?X-Amz-Expires=3600&amp;X-Amz-Date=20260303T030000Z&amp;X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Credential=DO801TYC4FCVNNEKURKM%2F20260303%2Ffra1%2Fs3%2Faws4_request&amp;X-Amz-SignedHeaders=host&amp;X-Amz-Signature=d10a6e13a18d6ac3f572f7cef5ca45be1632a8b372cc047337cf0f45d98dde9e">You can filter your logs by:<ul><li>IP Address</li><li>Country</li><li>Endpoint</li><li>Response Status</li></ul>

The Foreplay API allows you to access any Foreplay data to build on-top of our advertising database of over 100m ads or build custom agentic workflows in platforms like N8N, Gumloop or Zapier.

Getting started with the Foreplay API

Feedback

Roadmap

Zach Murray

Best steps on getting started with Foreplay.

Getting Started

The TLDR on how Foreplay can help you scale your ad creative workflow and performance. 

WTF is Foreplay??

Learn how to get the most out of the Foreplay Chrome Extension to save ads and analyze your competitors.

Chrome Extension

Save, organize and share advertising inspiration

Swipe File

Learn how you can save and share inspiration from anywhere while doing creative research or simply scrolling on social.

Saving & Sharing Ads

Folders and boards is the main organizational structure for everything in your Foreplay account. Learn how to keep your team organized. 

Folders & Boards

Custom tags and ratings in your Swipe File allow you to filter and organize ads more broadly beyond boards and folders. 

Tags & Ratings

To find specific ads broadly across your entire Swipe File you can use filters or sort orders. Here's how to get the most out of filtering.

Filters & Sorting

All ads saved to Foreplay are automatically analyzed with AI allowing you to reverse engineer the pain points, emotional drivers, creative targeting and more. 

AI Analysis

All video ads saved to Foreplay are automatically transcribed for free with AI allowing you to remix scripts with ease. 

Free Transcription

Commenting allows you to add notes to individual ads in Foreplay to be viewed by your entire team. Here's how to add and manage comments: 

Commenting

In addition to sharing public links to ads you can also embed individual ads in your website or in anyplace that iFrame embeds ads are supported. Here's how to embed an ad: 

Embedding an Ad

After you have saved ads you can delete them from your Swipe File or download them locally to your device. Here's how to do both. 

Download & Deleting

If you have a collection of old screenshots or ads - you can upload them to your Swipe File here's how to get it done. 

Manual Upload & Bulk Download

Searching your Swipe File by keyword is the easiest way to find ads that you can't find in your boards.

Search Swipe File

Nathan Raymant

Jack Kavanagh

Performance reports & analytics through a creative lens.

Lens

Leverage your performance data into creative insights so you can produce more winning ads.

Getting Started with Lens

The Dashboard is your mission control in Lens.
It gives you a real-time snapshot of how your ad account is performing — no digging, no guesswork.

Dashboard

Learn how to create and leverage the Top performing report type using lens. 

Top Performing Reports

Comparison Reports help you uncover high-level trends across your account—whether you're analyzing funnel stages, product lines, promotional angles, messaging, talent, or more. If it's reflected in your Ad, AdSet or Campaign name - you can compare it. Use this feature to spot what’s working, what’s not, and where to optimize.

Comparison Reports

The creative test's dashboard allows you to define targets and easily see whats working among your new creatives.

Creative Tests

Not all metrics matter equally to every team. That’s why Lens lets you fully customize your column view—so you can focus only on the data that matters most and create presets to be used across your entire account.

Customizing Columns

Learn how to create a external link to share reports with users inside your Foreplay team or as a guest - perfect for agencies looking to share reports with clients.

Share a Report

Learn how to filter your reports to narrow down the segment you want to analyze, creating contextual creative reports. 

Filters

Learn how to edit and manage your account settings for each ad account in Lens.

Lens Account Settings

Wondering if your performance is actually good? With Benchmarks in Lens, you can compare your key metrics against real-time data from over 20,000+ advertisers—so you know exactly where you stand.

Benchmarking

Foreplay Scores offer a convenient way to see how your ad stacks up against all the other ads you've launched under your Lens brand.

Foreplay Scores

Custom conversions let you create rules for events, allowing you to measure more specific customer actions and the value they generate. Learn how you can utilize your custom conversions in Lens.

Custom Conversions

Summary Net Statistics in Lens tables help you see the overall performance of your filtered view at a glance. Let's discuss how we compute these statistics.

Table Net Results

The "Inspiration" tab in Lens gives you fresh, curated inspiration from Foreplay's Discovery library meaning you have fresh ad inspiration based on any account you have connected to Lens.

Inspiration in Lens

Learn how to export a Lens report as a CSV to be used further in Excel or Google Sheets.

Export a Report

Browse & save over 50M ads saved by other Foreplay users

Discovery

Discovery is the worlds largest community ad search engine. With over 70 million ads you can see a live feed of every ad saved by other Foreplay users and use advanced search to find new  trends, products and ad strategies. 

Getting Started with Discovery

More then a standard search bar, Discovery search allows you to query based on Keyword, Product Category, or creative target. Here's how to get the most from search: 

Search Discovery

The brands tab in discovery allows you to see the most popular brands in Foreplay, filter and search to dive into each brand and see all ads that have been saved by the Foreplay community. 

Brands Tab in Discovery

Experts are a collection of Swipe Files built by the Foreplay community. It allows you to see and track the ads that top experts are saving to their own Swipe File. You can apply to be listed as an expert here. 

Foreplay Experts

With over 70 million ads in the Discovery library, keyword searches and filters don’t always surface the juiciest bits of inspiration to the top. Here's how to use the shuffle button to get endless inspiration.

Shuffle Button

Track every ad your competitors launch on autopilot

Spyder

Track every ad your competitors launch and extract insights and inspiration from their creative strategy.


Getting Started with Spyder

Adding a brand to Spyder will track every ad they launch on all Meta advertising platforms 24/7 while keeping a complete historical record of their advertising.

Track Competitor with Spyder

This tab on a Spyder brand page allows you to view all of your competitors creative testing and track which ads they are keeping on vs which ads they are turning off.

Competitor Creative Tests

All video ads in Spyder are automatically transcribed allowing you to easily view all the hooks they are testing in one place.

Competitor Hooks

Spyder also tracks all the landing pages your competitors are running on paid social. Here's how to get the most out of the Landing Pages tab in Spyder. 

Competitor Landing Pages

Similar to competitor creative tests in Spyder, the timeline view is a complete historical timeline of your competitors creative launches that you can filter by date range. Here's how to use it: 

Timeline View

Turn advertising inspiration into actionable briefs

Briefs

Getting started with Briefs

Creating Briefs

Creating Brand Profiles

Everything from managing your subscription to trial end information.

Billing & Subscription

Foreplay has flexible plans for brands and agencies of all sizes. Learn more about the feature and usage options. 

Billing & Plans

Learn about Foreplay's enterprise features and how to sign up for the Enterprise plan and save up to 80% on your subscription.

Custom Plans

Trial Cancelation

Everything on editing your account, team, and preferences.

Profile & Account

Learn how to change your Foreplay account name and profile photo.

Edit Your Profile

Learn how to update the password to your Foreplay account.

Update Password

Change account admin or transfer your Foreplay account ownership to a new email.

Transfer Admin Rights

Foreplay is better with friends. Learn how to create teams and manage permissions for rockstar creative collaboration.

Teams & Members

Learn how to white label your share links for reports, ads and boards.

White Label Settings

Save ads natively while scrolling Instagram by connecting it with your Foreplay account. No account access required.

Connect your Instagram Account

Collaborate on Lens accounts with clients or external collaborators. 

Guest Users in Lens

Connect to competitor and performance data

The Foreplay API works on a credit system. Learn how to use and reload credits for the API. 

Credits & Pricing

This article is to highlight the most commonly used endpoints in the Foreplay API for full endpoint documentation go here: https://public.api.foreplay.co/docs