Scraping

Scrape public social profiles and Meta Ads Library for competitive intelligence.

Social Scraping

Scrape public profile data and recent media from Instagram or TikTok accounts. Tasks are async -- create a task, then poll for results.

POST/api/v1/scrape/social

Request Body

Parameter	Type	Required	Description
handle	string	Yes	Public username to scrape
platform	`"instagram"` \| `"tiktok"`	Yes	Target platform
callbackUrl	string	No	Webhook URL to notify on completion

Example

Create scrape task

curl -X POST https://api.wondercat.ai/api/v1/scrape/social \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle": "natgeo", "platform": "instagram"}'

Response (201)

{
  "scrapeTaskId": "st_...",
  "handle": "natgeo",
  "platform": "instagram",
  "status": "pending"
}

GET/api/v1/scrape/social/{taskId}

Response (completed)

Once complete, the task includes the profile and an array of recent media with engagement metrics.

{
  "scrapeTaskId": "st_...",
  "status": "completed",
  "profile": {
    "username": "natgeo",
    "name": "National Geographic",
    "bio": "Experience the world through the eyes of National Geographic photographers.",
    "followerCount": 284000000,
    "profilePicUrl": "https://..."
  },
  "media": [
    {
      "originalUrl": "https://...",
      "postUrl": "https://instagram.com/p/...",
      "caption": "...",
      "likesCount": 120000,
      "commentsCount": 3400,
      "postTimestamp": "2026-03-20T12:00:00Z"
    }
  ]
}

Meta Ads Library

Search the Meta Ad Library for competitor creatives.

POST/api/v1/scrape/meta-ads

Request Body

Parameter	Type	Required	Description
query	string	Yes	Search query (brand name, keyword, etc.)
countryCode	string	Yes	ISO country code (e.g. US, GB, FR)
searchType	`"page"` \| `"keyword"`	No	Search mode. Defaults to "keyword".
activeStatus	`"all"` \| `"active"` \| `"inactive"`	No	Filter by active/inactive ads. Defaults to "active".
sortBy	`"impressions_desc"` \| `"most_recent"`	No	Sort order for returned ads.
period	`"last24h"` \| `"last7d"` \| `"last14d"` \| `"last30d"`	No	Time window for the search results.
contentLanguages	string[]	No	Optional language filters.
publisherPlatforms	string[]	No	Optional publisher platform filters.
mediaType	`"all"` \| `"image"` \| `"video"` \| `"meme"` \| `"none"`	No	Filter by media type.
maxResults	number	No	Max ads to return

GET/api/v1/scrape/meta-ads/{taskId}

Response (completed)

{
  "scrapeTaskId": "st_...",
  "status": "completed",
  "ads": [
    {
      "title": "Spring Sale",
      "bodyText": "50% off all items...",
      "imageUrl": "https://...",
      "videoUrl": null,
      "isActive": true,
      "startDate": "2026-03-01",
      "endDate": null
    }
  ]
}

Download a Reel or TikTok

POST/api/v1/scrape/reel

Download a single Instagram Reel or TikTok video by URL.

Request Body

Parameter	Type	Required	Description
url	string	Yes	URL of the Instagram Reel or TikTok

Example

curl -X POST https://api.wondercat.ai/api/v1/scrape/reel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/reel/ABC123"}'

Response

Returns a scrape task ID and platform. Poll GET /scrape/social/{scrapeTaskId} until status is completed. The downloaded video appears in the media array of the scrape result.

Instagram downloads start in "pending" status; TikTok downloads start in "processing" (sent directly to the video worker).

{
  "scrapeTaskId": "st_...",
  "platform": "instagram",
  "status": "pending"
}