LinkedIn Ad Library via Scavio

Search the ads running across LinkedIn by keyword and/or advertiser, then open any ad in full with its creative, headline, format, who paid for it and the advertiser's company URL. Both endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Find LinkedIn ads for a keyword, topic or advertiser
• See what ads a company is running on LinkedIn and pull the creative
• Build a competitor swipe file of B2B / sponsored-content ads
• Get one ad in full: advertiser, ad copy, headline, format, media and who paid for it
• Do paid-social, demand-gen or ad-intelligence research on LinkedIn

Setup

Get a free API key at scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

If you do not have a key yet

An agent running this skill without SCAVIO_API_KEY set will get 401 on every call below. The whole path from nothing to a working key is self-serve:

1. Sign up at dashboard.scavio.dev - email or Google, no card required.
2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.

When the balance runs out the API answers 402 with a JSON body carrying billing_url. Topping up needs no code change - the same key keeps working. The smallest purchase is 2,500 credits for $25, and monthly plans work out cheaper per credit if the usage is steady rather than one-off.

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev. Every LinkedIn Ads endpoint costs 6 credits.

Parameters

ads/search

Provide a keyword or a company_id (or both).

ads/detail

Provide an ad_id or a url (one is required).

Scope notes

• ads/search requires a keyword or a company_id - a bare call with neither is rejected.
• search returns the ads on one page and a total_seen count; it does not deep-paginate the whole library.
• company_id is the numeric LinkedIn company id (the digits in a company URL like linkedin.com/company/1035), not the vanity handle.
• detail carries impressions and demographics only where LinkedIn publishes them - for most non-political ads these are null, and about.run_dates may be null too.
• The thumbnail, advertiser_logo and media[].url are LinkedIn CDN links - fetch them promptly.

Examples

import requests

BASE = "https://api.scavio.dev"
# Your key from https://scavio.dev. Load it from your environment or secret
# store in real code - keep it out of source control.
API_KEY = "sk_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search ads by keyword, restricted to the US
search = requests.post(f"{BASE}/api/v1/linkedin/ads/search", headers=HEADERS,
    json={"keyword": "ai search", "countries": "US"}).json()
print(search["data"]["total_seen"], "ads seen")
for ad in search["data"]["ads"]:
    print(ad["ad_id"], ad["advertiser"], ad["format"])

# 2. Every ad from one advertiser, by numeric company id
by_company = requests.post(f"{BASE}/api/v1/linkedin/ads/search", headers=HEADERS,
    json={"company_id": "1035"}).json()

# 3. One ad in full, by an id from search
ad_id = search["data"]["ads"][0]["ad_id"]
detail = requests.post(f"{BASE}/api/v1/linkedin/ads/detail", headers=HEADERS,
    json={"ad_id": ad_id}).json()
d = detail["data"]
print(d["advertiser"], d["paid_for_by"], d["headline"])

curl:

curl -s https://api.scavio.dev/api/v1/linkedin/ads/search \
  -H "Authorization: Bearer $SCAVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"ai search","countries":"US"}'

Response shape

Every response uses the envelope { data, response_time, credits_used, credits_remaining }. On search, data carries ads[] plus a total_seen count; on detail, data is the ad object with a media[] array and an about block.

Guardrails

• Every LinkedIn Ads call is 6 credits - more than the other social endpoints, so paginate deliberately.
• Never fabricate advertisers, ad copy, headlines or media. Only return what the API returned.
• impressions and demographics are usually null - do not invent spend or reach figures when they are not present.
• CDN media links expire - fetch them promptly rather than storing the URL.

Failure handling

• 400 means an invalid request - most often search called with neither keyword nor company_id, or detail with neither ad_id nor url. Fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 404 means the ad id or URL was not found.
• 429 means rate or usage limit exceeded. Wait before retrying. See rate limits.
• 502 / 503 mean the source is temporarily unavailable - wait a few seconds and retry.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.