Ad Library

Scrape and browse competitor ads from the Meta Ad Library.

POST /ad-library/scrape

Start a scrape job for a brand from the Meta Ad Library. The API will fetch all active and inactive ads associated with the brand page and make them available through the other Ad Library endpoints.

If the brand has already been scraped, the API returns the existing brand record immediately without starting a new job or charging credits.

Credit cost: 10 credits per new scrape job. Rate limit: 3 requests per minute.

Request body:

Field	Type	Required	Description
`url`	string	Yes	Meta Ad Library URL for a brand page

Response (new scrape):

JSON

{
  "job_id": "uuid",
  "status": "processing"
}

Response (brand already scraped):

JSON

{
  "job_id": "uuid",
  "status": "existing",
  "brand_id": "uuid"
}

The scrape job runs asynchronously. Poll GET /ad-library/brands to check when the brand and its ads become available.

Examples:

curl -X POST https://www.adsumo.ai/api/v1/ad-library/scrape \
  -H "Authorization: Bearer adsumo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&view_all_page_id=123456789"}'

GET /ad-library/brands

List all scraped brands across the platform. Useful for competitor research and ad inspiration.

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of items to return (1--100)
`offset`	integer	0	Number of items to skip

Response:

JSON

{
  "data": [
    {
      "id": "uuid",
      "name": "Brand Name",
      "meta_page_id": "123456789",
      "page_url": "https://facebook.com/brandname",
      "about": "Brand description...",
      "profile_picture_url": "string | null",
      "page_categories": ["E-commerce", "Retail"],
      "page_like_count": 50000,
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "pagination": { "total": 5, "limit": 20, "offset": 0 }
}

GET /ad-library/brands/{id}/ads

Get all ads for a specific brand. Sorted by start date (newest first).

Path parameters:

Parameter	Type	Description
`id`	UUID	The brand's UUID

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of items to return (1--100)
`offset`	integer	0	Number of items to skip

Response:

JSON

{
  "data": [
    {
      "id": "uuid",
      "brand_id": "uuid",
      "ad_archive_id": "string",
      "is_active": true,
      "start_date": "2025-11-01T00:00:00Z",
      "end_date": null,
      "body_text": "Ad copy text...",
      "title": "Ad Title",
      "cta_text": "Shop Now",
      "cta_type": "SHOP_NOW",
      "link_url": "https://...",
      "display_format": "video",
      "publisher_platforms": ["facebook", "instagram"],
      "media": [{"type": "video", "url": "string"}],
      "thumbnail_url": "https://...",
      "eu_total_reach": 150000,
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "pagination": { "total": 42, "limit": 20, "offset": 0 }
}

GET /ad-library/ads/{id}

Get full details for a single ad.

Path parameters:

Parameter	Type	Description
`id`	UUID	The ad's UUID

Response:

JSON

{
  "id": "uuid",
  "brand_id": "uuid",
  "ad_archive_id": "string",
  "is_active": true,
  "start_date": "2025-11-01T00:00:00Z",
  "end_date": null,
  "body_text": "Ad copy text...",
  "title": "Ad Title",
  "cta_text": "Shop Now",
  "cta_type": "SHOP_NOW",
  "link_url": "https://...",
  "display_format": "video",
  "publisher_platforms": ["facebook", "instagram"],
  "media": [{"type": "video", "r2_url": "https://..."}],
  "thumbnail_url": "https://...",
  "eu_total_reach": 150000,
  "created_at": "2026-01-15T12:00:00Z"
}