API Reference

Spreshapp Public API

Four REST endpoints. JSON responses. Real-time programmatic access to the Facebook Ads Library.

Base URL https://api.spreshapp.com

Format application/json

Authentication

All requests require an API key passed as a Bearer token. Generate a key from your API Access dashboard. Keys start with sk_sprs_ and do not expire.

Use with Zapier? Connect Spreshapp on Zapier

Authorization string header required

Bearer authentication: Bearer <token>

Example

cURL

curl -X POST https://api.spreshapp.com/v1/ad-search \
  -H "Authorization: Bearer sk_sprs_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "running shoes" }'

POST /v1/ad-search 1 credit per ad returned Try it

Search the Facebook Ads Library by keyword. Returns matching ads with creative metadata, media URLs, and landing pages.

Request body

query string required

Search keyword or phrase

active_status string optional

ACTIVE (default) | INACTIVE | ALL

media_type string optional

ALL (default) | VIDEO | IMAGE

countries string[] optional

ISO country codes e.g. ["US","GB"]. Default: ["ALL"]

cursor string optional

Pagination cursor from a previous response

cURL

curl -X POST https://api.spreshapp.com/v1/ad-search \
  -H "Authorization: Bearer sk_sprs_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes",
    "active_status": "ACTIVE",
    "countries": ["US"],
    "media_type": "VIDEO"
  }'

200

{
  "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..."
}

GET /v1/brand/page-search 5 credits per call Try it

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 required

Brand name to search. Minimum 2 characters.

cURL

curl "https://api.spreshapp.com/v1/brand/page-search?q=nike" \
  -H "Authorization: Bearer sk_sprs_<your_key>"

200

{
  "pages": [
    {
      "page_id": "15087023444",
      "name": "Nike",
      "category": "Sportswear Store",
      "likes": 37000000,
      "verification": "blue_verified",
      "image_uri": "https://..."
    }
  ]
}

GET /v1/brand/:page_id 1 credit per ad returned Try it

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 required

Facebook page ID from /v1/brand/page-search.

Query parameters

sort string default: longest_running

longest_running | newest

display_format string default: ALL

IMAGE | VIDEO | ALL

country string default: ALL

Comma-separated ISO codes. Default: ALL

cursor string optional

Pagination cursor from a previous response

cURL

curl "https://api.spreshapp.com/v1/brand/15087023444?sort=newest&country=US" \
  -H "Authorization: Bearer sk_sprs_<your_key>"

200

{
  "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
}

GET /v1/ad-details/:ad_archive_id 1 credit when details returned, 0 otherwise Try it

Return DSA transparency data for a single Facebook ad: total reach, age/gender breakdown, gender audience, and estimated spend. Only available for ads running in regions with transparency requirements.

Path parameter

ad_archive_id string required

Facebook ad archive ID from /v1/ad-search or /v1/brand/:page_id.

cURL

curl "https://api.spreshapp.com/v1/ad-details/1234567890" \
  -H "Authorization: Bearer sk_sprs_<your_key>"

200

{
  "1234567890": {
    "total_reach": 471000,
    "age_gender_breakdown": [
      { "age_range": "18-24", "male": 50000, "female": 60000, "unknown": 1000 },
      { "age_range": "25-34", "male": 80000, "female": 90000, "unknown": 2000 },
      { "age_range": "35-44", "male": 55000, "female": 65000, "unknown": 1500 },
      { "age_range": "45-54", "male": 30000, "female": 35000, "unknown": 500 },
      { "age_range": "55-64", "male": 15000, "female": 20000, "unknown": 300 },
      { "age_range": "65+", "male": 5000, "female": 8000, "unknown": 100 }
    ],
    "country_ratio": {
      "UK": 0.3,
      "DE": 0.1,
      "FI": 0.5,
      "FR": 0.1
    },
    "gender_audience": "mixed",
    "estimated_spend_usd": 5181
  }
}

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 /v1/ad-details/:ad_archive_id`	1 credit when details returned, 0 otherwise

Get started

Start building in minutes

Free accounts include 100 credits per month. No credit card required to get started.

Get your API key View API access