Docs — YouTube Ads

Build with YouTube ads.

Programmatic access to YouTube ad inventory — search advertisers, paginate by session token, and read normalized creative records the same way the dashboard does. One small REST surface, no Google API quota dance.

Base URL

https://api.adscrape.in

Content-Type

application/json

Auth header

X-API-Key

Start here

Introduction

The YouTube Ads API on AdScrape gives you the same data the dashboard renders, exposed as a small REST surface. Every call returns JSON with consistent envelopes — there are no XML or form-encoded responses. YouTube-specific endpoints, auth, and credit rules.

REST + JSON
UTF-8 JSON in/out. Errors and success share one envelope shape.
Brand & keyword search
Query by VidTao brand_id, channel name, or free-text keyword across creatives.
Per-key analytics
Every call logged with endpoint, status, latency, and credits spent.
Pay per ad returned
1 credit / ad delivered. Empty pages are free — terminate cleanly.
Managed VidTao backend
AdScrape signs into VidTao and refreshes Firebase tokens for you.
Soft launch
YouTube routes are preview today — billing flips on at GA.

0 → first response in 60 seconds

Quickstart

1. Create a key. Settings → API Keys → Create. Copy the sk_live_… once — you won't see it again.
2. Probe status. Hit GET /api/v1/youtube/status — a 200 means VidTao is configured server-side and you're good to scrape.
3. Fire your first search. Returns ranked creatives + a session_token you can drain page-by-page.

bash

curl -X POST https://api.adscrape.in/api/v1/youtube/search \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","max_results":25}'

Auth

Authentication

Every billable endpoint requires a key in the X-API-Key header. Bearer JWT works too if you're calling from a logged-in dashboard. Keys are scoped per user, support per-key RPM overrides, and revoke instantly from Settings → API Keys.

bash

curl -X POST https://api.adscrape.in/api/v1/youtube/search \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike"}'

Treat keys like passwords. Anything that calls this API with your key spends your credits. Rotate from Settings → API Keys if you suspect a leak.

Pricing

Credits & pricing

AdScrape bills in credits backed by a transparent USD rate. New accounts get 10 free credits. Every charge lands in your ledger at Settings → Billing.

EndpointPer-call rateUSDNotes

POST /api/v1/youtube/search
per ad returned
$0.05 / ad
Charged only for delivered creatives. Empty results cost 0.
POST /api/v1/youtube/suggestions
per result block
$0.01 / suggestion
Brand typeahead. Cached 1h on (query, region) — cache hits are free.
GET /api/v1/youtube/status
free
—
Service health probe. Always free.

Throughput

Rate limits

Rate limits are per API key, evaluated in 60-second windows. Bursting beyond the cap returns HTTP 429 with a Retry-After header. Plans inherit the master AdScrape limits — there is no separate YouTube tier.

PlanReq / minNotes

Free
30
Enough for ad-hoc tests + 10 free credits.
Starter
60
Solo marketers and side projects.
Growth
120
Agencies running multiple brands in parallel.
Scale
600
Pipelines, dashboards, and bulk research.

Error model

Error responses

Errors share one envelope shape: { "detail": "...", "code": "..." }. Treat any non-2xx as a no-charge — credits are debited only after the response is successfully streamed.

StatusReasonMeaning

400validation_error
Body or query failed Pydantic validation. The detail field names the offending field.
401missing_key
No X-API-Key header and no valid JWT cookie.
402insufficient_credits
Wallet would go negative — top up or upgrade plan.
429rate_limited
Per-minute cap exceeded. Honour Retry-After.
502upstream_error
VidTao returned a transient error. Retry with backoff.
503service_unavailable
VidTao session not yet authenticated server-side. Check /youtube/status.

Endpoint

Search creatives

POST/api/v1/youtube/search 1 credit / ad

Scrape YouTube ad creatives via VidTao. Pass a brand_id for the cleanest results, or a free-text query for advertiser-name fuzzy matching.

Request body

FieldTypeDescription

queryoptional
string
Free-text advertiser/keyword. One of query or brand_id required.
brand_idoptional
string
VidTao brand identifier from /youtube/suggestions.
max_resultsoptional
integer
Max creatives returned (1–100). Playground is clamped to 5.Defaults to 25.
regionoptional
string
ISO 3166-1 alpha-2 country code to scope creatives.Defaults to "US".
session_tokenoptional
string
Pass back to /search to paginate the same session.

Request

bash

curl -X POST https://api.adscrape.in/api/v1/youtube/search \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","max_results":25,"region":"US"}'

Response

application/json200 OK

{
  "summary": { "count": 24, "region": "US", "query": "nike" },
  "ads": [
    {
      "ad_archive_id": "yt_abc123",
      "advertiser": "Nike",
      "channel_id": "UCUF...",
      "title": "Just Do It — Spring 2026",
      "format": "skippable_in_stream",
      "duration_sec": 30,
      "first_seen": "2026-03-14T08:21:00Z",
      "video_url": "https://api.adscrape.in/m/yt_abc123.mp4"
    }
  ],
  "session_token": "yt_sess_5f8e...",
  "has_more": true
}

Endpoint

Brand suggestions

POST/api/v1/youtube/suggestions 1 credit / batch

Resolve a partial advertiser string to VidTao brand_ids. Use the brand_id from this response for the cleanest /search results.

Request body

FieldTypeDescription

queryrequired
string
1–60 chars. The partial brand name to expand.
limitoptional
integer
Max suggestions to return (1–20).Defaults to 5.

Request

bash

curl -X POST https://api.adscrape.in/api/v1/youtube/suggestions \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"nik","limit":5}'

Response

application/json200 OK

{
  "suggestions": [
    { "brand_id": "vt_nike",   "name": "Nike",            "verified": true, "country": "US" },
    { "brand_id": "vt_nikon",  "name": "Nikon",           "verified": true, "country": "JP" },
    { "brand_id": "vt_nikola", "name": "Nikola Motors",   "verified": false, "country": "US" }
  ],
  "cached": false
}

Endpoint

Service status

GET/api/v1/youtube/status free

Health probe. Confirms the server has working VidTao credentials before you spend credits.

Response

application/json200 OK

{
  "ok": true,
  "vidtao_authenticated": true,
  "last_token_refresh": "2026-05-16T08:00:00Z"
}

Next steps

The dashboard, your keys, and your billing live one tab away.

API keysCreate, rotate, scope by RPM PlaygroundTry this API in 60s, no key required Billing & creditsPlans, top-ups, ledger YouTube overviewBack to the platform tour Usage analyticsPer-key, per-endpoint, per-day ContactSales, support, or partnerships

Looking for the master reference? AdScrape's full cross-platform docs cover billing, webhooks, and shared schemas at /docs.

Build with YouTube ads.

Base URL

https://api.adscrape.in

Content-Type

application/json

Auth header

X-API-Key

curl -X POST https://api.adscrape.in/api/v1/youtube/search \ -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"query":"nike","max_results":25}'

curl -X POST https://api.adscrape.in/api/v1/youtube/search \ -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"query":"nike","max_results":25,"region":"US"}'

{ "summary": { "count": 24, "region": "US", "query": "nike" }, "ads": [ { "ad_archive_id": "yt_abc123", "advertiser": "Nike", "channel_id": "UCUF...", "title": "Just Do It — Spring 2026", "format": "skippable_in_stream", "duration_sec": 30, "first_seen": "2026-03-14T08:21:00Z", "video_url": "https://api.adscrape.in/m/yt_abc123.mp4" } ], "session_token": "yt_sess_5f8e...", "has_more": true }

{ "suggestions": [ { "brand_id": "vt_nike", "name": "Nike", "verified": true, "country": "US" }, { "brand_id": "vt_nikon", "name": "Nikon", "verified": true, "country": "JP" }, { "brand_id": "vt_nikola", "name": "Nikola Motors", "verified": false, "country": "US" } ], "cached": false }