API Reference
Spreshapp Public API
Three REST endpoints. JSON responses. Real-time programmatic access to the Facebook Ads Library.
https://api.spreshapp.comapplication/jsonAuthentication
All requests require a valid session JWT passed as a Bearer token. Copy your token from API Access after logging in.
Authorization string header requiredBearer authentication: Bearer <token>
Example
curl -X POST https://api.spreshapp.com/v1/ad-search \ -H "Authorization: Bearer <your_token>" \ -H "Content-Type: application/json" \ -d '{ "query": "running shoes" }'
Search the Facebook Ads Library by keyword. Returns matching ads with creative metadata, media URLs, and landing pages.
Request body
query string requiredSearch keyword or phrase
active_status string optionalACTIVE (default) | INACTIVE | ALL
ad_type string optionalALL (default) | VIDEO | IMAGE
countries string[] optionalISO country codes e.g. ["US","GB"]. Default: ["ALL"]
cursor string optionalPagination cursor from a previous response
curl -X POST https://api.spreshapp.com/v1/ad-search \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "query": "running shoes", "active_status": "ACTIVE", "countries": ["US"], "ad_type": "VIDEO" }'
{ "ads": [ { "ad_archive_id": "1234567890", "page_name": "Nike Running", "body_text": "Built for the roads you run.", "display_format": "VIDEO", "ad_started_on": 1714521600, "cta": "Shop Now", "landing_page": "https://nike.com/running", "video_url": "https://cdn.example.com/ad.mp4" } ], "next_cursor": "AQHRJLdt..." }
Search for a brand's Facebook page by name. Returns page IDs, categories, and follower counts.
Use the returned page_id with the brand active ads endpoint.
Query parameters
q string requiredBrand name to search. Minimum 2 characters.
curl "https://api.spreshapp.com/v1/brand/page-search?q=nike" \ -H "Authorization: Bearer <token>"
{ "pages": [ { "page_id": "15087023444", "name": "Nike", "category": "Sportswear Store", "likes": 37000000, "verification": "blue_verified", "image_uri": "https://..." } ] }
Returns all currently active ads for a Facebook page. Filter by format and country, sort by run length or recency, and paginate with cursors.
Path parameter
page_id string requiredFacebook page ID from /v1/brand/page-search.
Query parameters
sort string default: longest_runninglongest_running | newest
display_format string default: ALLIMAGE | VIDEO | ALL
country string default: ALLComma-separated ISO codes. Default: ALL
cursor string optionalPagination cursor from a previous response
curl "https://api.spreshapp.com/v1/brand/15087023444?sort=newest&country=US" \ -H "Authorization: Bearer <token>"
{ "ads": [ { "ad_archive_id": "9876543210", "page_name": "Nike", "body_text": "Just Do It.", "display_format": "IMAGE", "ad_started_on": 1709251200, "cta": "Shop Now", "landing_page": "https://nike.com/...", "image_url": "https://cdn.example.com/..." } ], "next_cursor": "AQHXtz9c...", "has_more": true }
Error codes
| Status | Error | Meaning |
|---|---|---|
| 401 | Unauthorized | Missing or invalid JWT token |
| 403 | feature_not_available | Account does not have API access |
| 429 | credits_exhausted | Monthly credits used up. Check reset_at in response. |
| 400 | Bad request | Missing or invalid request parameters |
| 503 | Service unavailable | Upstream error, retry with exponential backoff |
Credits
Every account gets 100 free credits per month, including free accounts. Additional credits are available as a paid add-on (5,000 credits for $3/month). Credits reset on the 1st of each month and do not roll over.
| Endpoint | Cost |
|---|---|
POST /v1/ad-search | 1 credit per ad returned |
GET /v1/brand/page-search | 5 credits per call |
GET /v1/brand/:page_id | 1 credit per ad returned |
Get started
Start building in minutes
Free accounts include 100 credits per month. No credit card required to get started.