Google Ads Transparency Scraper — Fast, Reliable, Watch Mode
Pricing
from $1.00 / 1,000 ad scraped (1 result)s
Get an advertiser's Google ads by domain, advertiser ID, or Transparency Center URL. Returns creative images, OCR'd headline/body text, format, and shown dates. Watch mode returns only new ads.
A second, deeper adversarial pass, done because the first one was asked to find what it missed rather than re-confirm what it already found.
shouldEscalateAdTextFault(), a pure function with no
dependency on tesseract or real images, so it is directly testable. Four tests added, each
confirmed to fail against a deliberately broken version of the function.README.md's "Input reference" line never mentioned extractAdText (or the pre-existing
resolveAdvertiserInfo) among the key options — a plain omission from the line that lists every
other boolean flag. Added both.creativeText at all, despite it being documented
two sections above as a real output field. Rather than splice a plausible-looking value onto the
existing example — the exact mistake this project's own memory warns against — captured a fresh,
real run against the same advertiser (patagonia.com) with the option on, and replaced the whole
block with what actually came back, verified field-by-field against the raw JSON by script rather
than by eye. Caught myself doing it wrong once: a first draft "corrected" two of the OCR's own
misreads (Rucksacke, Ausriistung) before shipping it, which would have quietly claimed better
accuracy than the feature has. Reverted to the literal reading.ads.sumitsubo.com crawl page had no favicon and no Open Graph / Twitter Card tags. Not
a functional defect, but a real completeness gap on a page meant to be linked and found. Added a
minimal inline SVG favicon (no external asset) and og:/twitter: tags matching the existing meta
description.parse.js, rpc.js, watch.js in full; main.js end to end in one
pass rather than in the fragments the first review touched; test/billing.test.js's dynamic
cross-check (it greps main.js for every safeCharge/exhausted call and asserts the set matches
CHARGE_EVENTS exactly — this would have caught a misspelled ad-text-extracted on its own);
package-lock.json (no artifactory drift, no unexpected new dependencies — OCR shells out to the
tesseract binary rather than adding an npm package); Dockerfile (apk layering and the
build-time tesseract --version smoke test are both sound).curl against the same URL showed
the correct, current content immediately — the same 15-minute WebFetch cache staleness already
logged once earlier today, not a second real regression.npm test: 95/95 pass (4 new regression tests).A full adversarial re-verification of everything shipped so far today, done because "it works" had not yet been checked against "it does what it claims to do" as a separate question.
ocrAvailable() cached a false result forever, on the same terms as a proven true — but the
tesseract binary the Dockerfile installs cannot un-install itself mid-run, so a false can only
mean a passing exec fluke (the same fractional-CPU contention measured in 0.2.35), never a real
absence. One unlucky first check silently turned the feature off for every ad after it, reported
as no-binary even though the binary was fine. Now only true is cached; a false is re-checked
next time. Regression test added (ocrAvailable now accepts an injectable check for exactly this),
confirmed to fail when the old caching is restored.no-binary (genuinely run-wide — the binary either exists
for the whole run or it does not) from too-big / tesseract-failed on one specific image (not
necessarily run-wide at all). Generalising a whole run's health from one data point is exactly the
mistake 0.2.33 corrected in the README; the code was making the same one. no-binary still warns
immediately; the other two now only escalate to a run-wide warning after recurring three times.description didn't mention the thing it now does. Set the same day OCR
shipped (0.2.32) and never revisited, it listed inputs and outputs but not creativeText — the
string an AI agent reads via the Apify MCP server to decide whether to call this Actor never
mentioned its actual differentiator. Updated live (API, since apify push does not touch this
field — see 0.2.32) and in seoDescription, both within their character budgets.billing.js's own error message said "the four billed events" — there are five. A stale
count left over from before ad-text-extracted existed, in a customer-facing warning about
matching Console's Monetization config to the code exactly. Now names them instead of counting them.docs/PROSPECTS.md still told the reader not to promise ad copy — the opposite of current
reality. Section 6 was written before OCR existed and was never revisited after it shipped
later the same day; an outbound pitch built from that file would have avoided mentioning this
Actor's actual differentiator. Rewritten to state what shipped and the honest OCR caveats to pair
with it.docs/STORE_LISTING.md's pricing table was missing the fifth event entirely, and its own
reasoning for the short description ("says nothing about ad text — the source does not carry it")
had gone stale the moment OCR shipped. Both synced.CLAUDE.md's "next action" pointed a future session at HANDOFF.md's 2026-08-17 pre-launch
re-entry point — describing build 0.2.17, private, not yet monetized. The Actor has been public
and iterating for 63 builds since. This is the first file any future session reads, so a stale
pointer here would have cost real time. Now points at the actual current state and at
docs/PROSPECTS.md's own "next steps" section, which is where that decision now lives.creativeText Overview column, shipped
and pushed to the platform earlier today) had never actually been committed to git — the working
tree and the repository had quietly drifted apart. Committed separately before this entry.npm test: 91/91 pass (2 new regression tests for the availability-caching fix).Adds creativeText to the Overview dataset table. No code change.
creativeText/creativeTextSource from the integration test that checks every declared
column is actually emitted: this one only populates from a real Google-hosted image and a locally
installed tesseract binary, neither of which the fake RPC fixture used in tests can produce.
Covered instead by ocr.test.js directly and by the live platform run already recorded in 0.2.34.Fixes a real intermittent failure in 0.2.34's ad text extraction, found by running the new feature back-to-back on the platform rather than trusting one green run.
OCR_TIMEOUT_MS was too tight, and it was silently killing tesseract. Repeated runs on the
identical 139KB creative measured 482ms, 578ms, 5,247ms, 13,141ms and 17,955ms - a 37x spread with
no correlation to image size - and a further run was killed by SIGTERM at exactly 20,023ms, the
old timeout. A single call made afterward, with no back-to-back runs ahead of it, took 1,268ms -
so most of that spread was contention from testing this fix by firing repeated calls at the same
Actor in quick succession, not a property of a normal run. Raised to 90s anyway: a customer's own
concurrent tasks could recreate the same contention, it costs nothing on a genuine hang (the
caller still gets unreadable for that one ad), and it clears the worst self-inflicted run
measured (65s) with real margin.err.stderr was
empty on a SIGTERM kill, so the old code fell back to a message that said nothing more. Failures
now report signal=, exitCode=, killed=, and afterMs= explicitly, which is what made this
fault diagnosable in the first place rather than looking identical to a corrupt image.RUN_SUMMARY.adText now also carries maxMs/lastMs, so a future slowdown shows up in the
summary instead of requiring another round of manual repeated runs to catch it.fetchCreativeDetails or downloadAssets, so a customer running extractAdText alone with a
large maxItems got no warning before the same TIMED-OUT risk those two were added to prevent.
Measured throughput with this option alone — 10 ads in 294.7s, 2.0/min — is not faster than the
other two extras together (2.9/min), because it still costs a rate-limited fetch per ad when the
image was not already downloaded. The warning now triggers on any of the three, using the slower
of the two measured rates so the estimate stays conservative either way. Regression test added,
confirmed to fail when extractAdText is dropped from the trigger.Returns what the ad actually says. New opt-in: Read the ad text out of the creative.
GetCreativeById response for a text ad is 306 bytes and the only prose in it is an <img> tag,
and nothing was being dropped in parsing. The words exist only as pixels, so the Actor now reads
them, and returns them in creativeText.ad-text-extracted at $0.002 fires on ads that produced
legible text; a video ad or a wordless banner is free. The floor is a letter count rather than a
string length on purpose: tesseract returns punctuation noise on pure artwork, and billing for
|| -- .,; would be billing for nothing. Pinned by a test that fails when the floor is removed.creativeTextSource says where the value came from. It is ocr — a reading of a picture, not
a field Google published — so downstream code never has to guess how much to trust it. Expect the
occasional misread; the listing says so rather than letting a buyer discover it..png fails to decode with an empty stderr.
Measured on the platform: no extension at all extracted 1 ad in 3, forcing .png got 2 in 3, and
sniffing the bytes gets 6 in 6 on the same advertiser.null could not tell a wordless ad from a fetch that never happened or a decoder that
crashed. RUN_SUMMARY.adText now splits attempted / extracted / noImage / fetchFailed /
unreadable, and a fault that is not simply "this ad has no words" is said once in the log._= propellant.media -> propellant.media), and only from
the front of a line, and only before a word character or / — a line starting with $ or # is
ad copy and keeps it.npm test: 88/88 pass.Corrects a false claim shipped in 0.2.31, four builds ago. Documentation only.
Rewrote the Actor description for the reader that actually uses it. No code change.
Documentation only — no code change. Both entries came out of running this Actor against real prospect domains and reading what actually came back.
fetchCreativeDetails and downloadAssets on — the variants carry
imageUrls only, previewHtml is a bare <img> tag, and the archived asset is a PNG. Nothing is
being dropped in parsing; the payload has no headline or description string in it. The note now
names the fields that really are advertiser-written (advertiser and legal names).Found what was actually failing Apify's own daily health check, by pulling the one run its
notification email could point to (meta.origin: "TEST", a run under a different account than
the developer's own).
ads-transparency-state
was opened unconditionally at startup even though it is only read or written when onlyNewCreatives
is on — persistState() already no-ops otherwise. Apify's health check runs the Actor's prefilled
input (onlyNewCreatives: false) under an account whose token cannot create a new named store, so
every one of its runs passed input validation with nothing wrong to report, then crashed at that
line anyway with a raw 403 insufficient-permissions. Three days of that is what triggered "Under
maintenance." The store is now opened only when watch mode is actually on.default on queries (reverted — it silently added a nike.com search to
advertiserIds-only calls, which is a worse bug than the one it would have masked), the datacenter
proxy default (already fixed in 0.2.26, reconfirmed here with a live 100/100-ad run), and a
transient Google rate limit (the exact prefilled input succeeded standalone, which is what made the
permissions error in the real failing run's log worth going and reading).onlyNewCreatives: false never makes
either way. Confirmed that the fix's own guard is what matters by deliberately reverting it: a
behavioural test asserting the store directory was never created still passed against the broken
version, so it was replaced with one that pins the source shape instead — that one fails when
reverted.npm test: 79/79 pass.Investigated whether an Actor owner can see why someone else's run failed. The answer is: only if that person does one of two things, and there was no way to ask them to. This closes that gap.
npm test: 78/78 pass.Priced for what this Actor is actually used for.
A review pass over 0.2.26 found it breaking its own rule in one corner.
runStartCharged was set when the charge was attempted, not when the
platform confirmed it, so a run whose Max total charge is set below the run
start would have been told it paid for something it did not. The flag now
reads the platform's own chargedCount, and the one-shot guard is a separate
variable so the two questions — did we ask, did they take it — cannot be
conflated again. Pinned by a test that fails against the optimistic version.npm test: 78/78 pass.The Actor's default proxy setting was the reason every external run of it had
failed. Found by running the same search twice, a minute apart, from the same
account: apifyProxyGroups: ['RESIDENTIAL'] returned 10 of 10 ads in 10.4
seconds over 4 requests, and { useApifyProxy: true } — the datacenter pool,
and this Actor's default — returned 0 ads with 6 of 6 requests answered HTTP 429.
actor-start used to be charged
before the first request, so those four runs were billed $0.03 each for
reaching no data at all. It is now charged on the first HTTP 200 from Google —
a quiet watch run that legitimately finds nothing new still pays it, as the
README promises, and a run blocked at the door pays nothing. One-shot twice
over: a flag in the loop and isOneTimeEvent on the platform's price list.RUN_SUMMARY.proxy records the group and monetization
records whether the run start was billed — the questions this defect took two
days to answer, because nothing in the summary distinguished "advertiser has no
ads" from "this run never reached Google".npm test: 78/78 pass.An external trial run failed three times in a row (publicActorRunStats30Days: 3/3 FAILED, $0
earned). Reproducing prefill and boundary values by hand traced it to raw Node stack traces
surfacing on invalid input — the same class of bug 0.2.24 fixed for individual fields, but not
funnelled through one exit path. Closed here, plus one more input the earlier pass missed.
queries/
advertiserIds entries, an unrecognised region, an unknown platform, a non-ISO date, or no
input at all used to each crash differently ({} alone produced a raw stack trace); all five
now produce a one-line Actor.exit({ exitCode: 1, statusMessage }) a customer can act on.proxyConfiguration was the one input never funnelled. The Console proxy editor can only
send valid combinations, but a run started through the API can send anything the SDK itself
rejects — a subdivisionCode without countryCode, custom proxyUrls combined with
useApifyProxy, or a proxy group the account has no access to. Actor.createProxyConfiguration()
was called outside the validation block, so any of those crashed the run before actor-start is
charged (no money lost, but the same broken first-impression the other four had). Moved inside
the same try/catch. Regression test added: an invalid subdivisionCode now exits cleanly
instead of throwing.npm test: 64/64 pass.Everything an independent review raised on publication day, closed. The two that mattered were about money and about a promise we had made in public.
client a folded to client_a; two projects then treated each other's ads as already seen and
the symptom was an alert that never arrived. Folded keys now carry a hash of the original; keys
that need no folding are untouched.queries: [123] ended the run with
q?.trim is not a function; a startUrls entry with no url was dropped in silence.RUN_SUMMARY.monetization.assumed records charges the platform never confirmed a count for, so
the health figures cannot quietly become our own assumption. Measured on the platform: 0.Publication day, and a third independent audit run against what was actually shipped. The audit found one live falsehood — introduced by the listing work itself, hours earlier.
actor-start on every run, including the ones that return nothing. The
caption now states the $0.03 run start and says plainly what the on-screen $0.001 is. The mistake
was a 30× understatement of the recurring cost of the product's headline use case.Publish on Store stays disabled without
.actor/output_schema.json; the dataset views in actor.json are not enough. Added, with the
dataset, the archived images and RUN_SUMMARY as its three outputs.CHARGE_EVENTS. The platform's two
default events (apify-actor-start, apify-default-dataset-item) were removed — leaving them
would have billed a second time on top of actor-start and ad-scraped.A second independent audit, run against the finished 0.2.18 tree. Most of what it found had been introduced by 0.2.18 — guards that looked present and never fired, and claims that had drifted away from the code.
apify push does not read .dockerignore. That file governs the built image; the source
uploaded to the platform is filtered by .actorignore, which did not exist. Competitor names and
pricing, the retreat lines, the market research and an employer's internal hostname would all
have been stored as Actor source, with nothing failing to warn about it. Added .actorignore;
the checklist now says to eyeball the Console Source tab after pushing.err.cause and the branch added in 0.2.18 was unreachable — the SSRF guard worked, but silently,
which is exactly the failure it was supposed to make visible. Detection is now a tested predicate
(isRefusedRedirect) that walks the cause chain, and RUN_SUMMARY.refusedRedirects counts them.<img> tags produced 300
chargeable downloads. Capped at 10 per ad, and the cap is now shared by both paths.previewImageUrl came straight
from advertiser-written markup and the dataset table renders it as an image, so a 1x1 on the
advertiser's own host would have told them who was watching them and from where. Image fields are
now filtered to Google hosts; anything else is kept in externalImageUrls, which nothing fetches.ad-scraped to ads-scraped in the code
left every test green while that event was given away free. A test now pins the strings in
main.js to the priced set in billing.js.\\+\/ decode was quadratic on a long run of backslashes in an advertiser-influenced payload
(measured 5.7s at 128k); bounded now.npm run verify:images reported success when it had verified nothing — a rate-limited run
produced "0/0 resolved cleanly" and exit 0, which is the only real-data gate behind the
broken-URL fix. It now fails on an empty result, as does verify:watch.youtubeVideoId says it needs Archive creative images, "permanent copies" is now
storage-retention-honest, the acceptance-test table no longer claims v0.2.18 tests were already
run at v0.2.3, and the compliance note no longer says "no personal data" where the README already
said the opposite.Independent pre-publication review. Everything here is a defect that left the Actor running and reporting success while producing wrong output, wrong money, or a wrong promise.
" (written \x26quot;), and the extractor decoded
only the JavaScript escape layer — so the delimiter and the text after it stayed glued to the
URL. Three of the four rows in the sampled output carried a 404 URL in previewImageUrl, which
is the field the dataset's Creative column renders. The same bug also mangled legitimate
& separators. Ampersands are now resolved to a fixed point in all four forms Google uses
(\x26, &, &, and double-encoded), quote entities are decoded, and only a surviving
quote truncates the URL — cutting at an ampersand would drop the query string and 404 just as
surely.previewImageUrls was always empty for image ads — the field the README documents, while the
resolved URL went only into the singular previewImageUrl. The list and the thumbnail now
describe the same creative.incompleteSeeds) and keeps reporting watchCoverage: 'partial' until some run finishes it;
otherwise run 2 walks down to its own watermark, calls itself covered, and bills the unread tail
as launches under a healthy-looking summary.RUN_SUMMARY.monetization (active, problem, unpricedEvents)..actor/actor.json promises the store table
is actually emitted, so a renamed field cannot turn into a silently blank column.0.1.0, and RUN_SUMMARY now reports stateCheckpoints
so the migrate/abort save path — implemented but never yet observed firing — can be confirmed
from a real run instead of assumed.npm run verify:images,
verify:watch, verify:misc in tools/): every emitted image URL fetched and returned HTTP 200
across text, image, shopping and video ads; a real two-run watch converged to one request and
zero output; overlapping searches produced no duplicate rows.Findings from running the product the way a customer would, at real scale.
previewImageUrls was empty for precisely the ads a creative researcher wants. Resolved:
10/10 image ads now carry a thumbnail and archive, against 0 and 2 before.youtubeVideoId / youtubeUrl, extracted from a response we already
fetch, so it costs nothing. Every video ad also gets a thumbnail via YouTube's own URL.
Duration is deliberately not included — it is not in the payload, and inventing it would
mean taking on the YouTube Data API for a secondary field.Adversarial pass over the real output of a real platform run, before publication.
regionHint. It was derived from a response field whose meaning was a guess.
Measured on a region=JP search it returned values like 1420 and 1717, plus stray country
codes, and never JP — a field that is wrong in a plausible-looking way is worse than no field.raw. The entire advertiser lookup payload was being copied into every row.
Rows are now 707 bytes instead of 1,375.<img src> is untrusted input; unrestricted, it was an outbound-request
primitive and a way to make the customer pay to archive arbitrary files. Also capped at 25 MB."2026-7-1" sorts
above every real timestamp).Pre-launch hardening. Everything here came out of re-measuring the live RPC.
lastShown-descending (measured), so a
watch run reads only down to where the previous run got to. Monitoring a 100k-creative
advertiser costs a few requests per run instead of ~1,000.lastShown on every live
ad, so the old "new or updated" rule returned the advertiser's whole active inventory on every
scheduled run — expensive for the user and useless as an alert. includeUpdated (default off)
brings the old behaviour back for activity tracking.fullScanEveryNRuns, default 7) and an overlap window
(overlapHours, default 24) so the shortcut cannot silently lose an ad; a run cut short by
maxItems now forces a full rescan next time instead of remembering an incomplete pass.Initial release.
onlyNewCreatives + stateKey): persistent per-project memory, isNew / isUpdated flags, outputs only launches and refreshes on scheduled runs.actor-start, ad-scraped, creative-detail, asset-downloaded.