Overview
MTWSPY public API — search Facebook and Instagram ad creatives, delta feed, landing pages, webmasters, affiliate networks and folders.
The API serves the same Facebook and Instagram creative database as the MTWSPY dashboard: search by filters, new creatives since your last check, landing page links and archives, webmasters, affiliate networks and your folders. Auth is a Bearer token, responses are JSON.
Base URL
https://app.mtwspy.com/public/v1
Quick start
Check your remaining views (this call is free):
curl https://app.mtwspy.com/public/v1/usage \
-H "Authorization: Bearer mtw_live_your_key"Five nutra creatives targeting Poland:
curl -G https://app.mtwspy.com/public/v1/creatives \
-H "Authorization: Bearer mtw_live_your_key" \
-d geo=PL -d vertical=nutra -d limit=5Keys are created in the dashboard, in the API section. See Authentication.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /creatives | Search by filters, cursor pagination, delta feed |
GET | /creatives/{id} | Full card: landing page link and files |
GET | /creatives/{id}/landing | Landing archive link |
GET | /webmasters | Search webmasters (teams) |
GET | /webmasters/{code} | Webmaster dossier |
GET | /networks | Affiliate networks |
GET POST | /folders | Your folders: list and create |
GET PATCH DELETE | /folders/{id} | A folder: contents, rename, delete |
POST DELETE | /folders/{id}/creatives | Add or remove a creative |
GET | /usage | Plan, remaining views and AI credits |
GET | /balance | Referral balance |
Search, cards and landing pages are also available to AI assistants through the MCP server.
Response format
Success:
{ "data": { "...": "..." }, "meta": { "request_id": "fed23a8edcf5399e" } }Error:
{ "error": { "code": "quota_exhausted", "message": "..." }, "request_id": "fed23a8edcf5399e" }Handle errors by code: the message text may change. Every response carries a
request_id, also in the X-Request-Id header — support will ask for it.
Error codes
code | HTTP | When |
|---|---|---|
missing_token / invalid_token | 401 | No token, or the token is wrong |
key_revoked | 403 | The key was revoked |
plan_no_api | 403 | Your plan has no API access |
subscription_expired | 403 | Subscription expired |
quota_exhausted | 403 | No views left |
creative_not_served | 403 | The creative was never returned to your account, so it can't go into a folder |
invalid_body | 400 | The request body isn't a JSON object |
invalid_parameter | 422 | A parameter is invalid |
not_found / no_landing / landing_unavailable | 404 | Not found, the creative has no landing page, the archive is missing from storage |
method_not_allowed | 405 | The path doesn't support this method |
already_in_folder / folder_limit / folder_full | 409 | Folder limits |
rate_limited | 429 | Too many requests per minute |
daily_limit_reached | 429 | Daily limit on webmaster dossiers or folder changes |
download_limit | 429 | More than 30 landing downloads in an hour |
search_unavailable | 503 | Search is temporarily down |
Views and limits
The API has no separate quota. It spends the same view balance as the feed on the website:
one creative returned by /creatives costs one view. The balance is
topped up when your plan renews or when you buy extra views in the dashboard.
| Request | Views |
|---|---|
/creatives | One per returned card. Repeating the same page with the same parameters within 2 hours is free |
/creatives/{id}, /creatives/{id}/landing | Free |
/webmasters, /networks, /folders, /usage, /balance | Free |
Once views run out, /creatives returns 403 quota_exhausted. Everything else keeps working.
Requests per minute depend on the plan:
| Plan | Requests per minute |
|---|---|
| Basic, Team | 30 |
| Team API | 60 |
Some endpoints have their own limits: 30 landing downloads per hour, 10 webmaster dossiers per minute and 200 per day, 30 folder changes per minute and 500 per day.
Current balances are in the X-Quota-* and X-RateLimit-* headers and in meta.api_limit.
To check them on their own, call /usage.
Limits are per account, not per key. Team members spend the owner's views. Reissuing or revoking a key doesn't change the balance.