Research competitor ads

Search real ads from the Facebook Ad Library.

Research lets you pull the ads a company is running on Facebook — useful for competitor analysis and creative inspiration.

Research runs as a job: you quote it, confirm it, then read the result when it’s ready. It costs 1 credit per request (and nothing if it fails or returns nothing).

1. Quote

Give the company’s Facebook Page ID and your filters. Set quote_only: true to see the price first:

curl -X POST https://api.roasos.com/v1/research/jobs \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: nike-research-001" \
  -H "Content-Type: application/json" \
  -d '{
    "capability_id": "research.facebook-company-ads@1",
    "target": { "kind": "page_id", "page_id": "15087023444" },
    "filters": { "status": "ACTIVE", "media_type": "ALL", "sort_by": "relevancy_monthly_grouped" },
    "page": { "max_pages": 1, "max_results": 30 },
    "freshness": { "max_age_seconds": 21600, "allow_stale": true },
    "quote_only": true
  }'

You get back a quote_id and maximum_credits: 1.

2. Confirm

Send the same body with the quote_id (and the same idempotency key) to start the job:

{
  "data": {
    "kind": "research_job",
    "id": "c70f0c64-...",
    "status": "queued",
    "reserved_credits": 1
  }
}

3. Check status

curl https://api.roasos.com/v1/research/jobs/c70f0c64-.../status \
  -H "Authorization: Bearer roasos_sk_..."

The status moves from queued → processing → succeeded (or failed).

4. Read the result

curl https://api.roasos.com/v1/research/jobs/c70f0c64-.../result \
  -H "Authorization: Bearer roasos_sk_..."

You get normalized ad records with source and provenance — what was observed, and when — kept separate from any inferred signals.

Freshness and caching

max_age_seconds — how fresh the data must be. If we have a recent enough result cached, you get it instantly and aren’t charged.
allow_stale — accept slightly older cached data rather than always fetching live.