AgentQL vs Playwright Selectors: What Breaks First

v4 is the column that should temper any enthusiasm for built-in locators. "In stock" became "Available now", "Add to basket" became "Add to bag". No markup changed at all. get_by_text("In stock") went from 20 matches to zero, and so did get_by_role("button", name="Add to basket").

Playwright's semantic locators are semantic about two axes, role and accessible name. Role is genuinely structural and held everywhere. Accessible name is a string, and a string is content, so pinning one is no more durable than pinning a class. Rewriting a stock badge is a copy ticket a content editor files, not an engineering change, and it will break a getByText scraper on a page whose DOM is byte-identical.

This is the precise gap AgentQL is selling into. A query that says availability(whether the item is in stock) is asking about meaning, and meaning did not change between "In stock" and "Available now". Whether AgentQL resolves that correctly on this fixture I cannot tell you, because resolving it requires a paid key and a network call, and I am not going to report an unmeasured number as a result. What I can show is my own stand-in paying the price of the same problem: when I wrote a locator to find the stock paragraph without AgentQL, I had to feed it re.compile(r"In stock|Available now"), which means I had to already know both strings. A semantic engine's pitch is that you do not.

One more Playwright behaviour to keep in the frame, from the locators doc: "Locators are strict. This means that all operations on locators that imply some target DOM element will throw an exception if more than one element matches." Counting with .count() is exempt. That strictness is the loudness. A locator that suddenly matches two things raises instead of silently taking the first.

AgentQL's own words, from its query-language concepts page, with no measurement from me attached:

• Queries are described as self-healing: "in the face of dynamic content and changing page structures, AgentQL still returns the same results."
• "Elements are found based on their meaning and context, not just their position in the DOM, making them more: Stable even when website layouts change over time."
• "a single AgentQL query could extract listing data from both Redfin and Zillow, and continue to function even after site updates, A/B tests, and even redesigns."

Those are vendor claims. They are also the right claims to make for this product category, and the v1/v3 inversion above is the reason the category exists. Treat the specific durability as unverified until you have run your own targets against your own key.

Maintenance, from registries and the GitHub API on 9 October 2026, since "actively developed" is a claim that needs dates:

Read that carefully rather than as a scoreboard. AgentQL is maintained, not abandoned: the repo took commits on 1, 2 and 8 October 2026. The five most recent were a secrets-scanner workflow edit, three dependency bumps (urllib3 2.7.0 to 2.8.0, axios 1.18.1 to 1.20.0, brace-expansion 1.1.18 to 1.1.21) and a CODEOWNERS change, so housekeeping rather than feature work. The PyPI package has shipped 47 releases since 0.3.0 on 2024-03-25. What the dates do say is that the cadence slowed: the newest Python release is from 13 May 2026, roughly five months before this post, and the JavaScript package sits a minor version behind at 1.18.1 from February 2026. Playwright cut 1.64.0 on 7 October 2026, two days before this post, and publishes a nightly alpha every day. If your team writes JavaScript, note that version skew explicitly, because features in the 1.19.0 release notes such as the TF_BROWSER remote-browser profile are Python-only until the JS package catches up.

The REST surface is a single POST:

curl -X POST https://api.agentql.com/v1/query-data \
  -H "X-API-Key: $AGENTQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ products[] { name price(integer) } }",
    "url": "https://books.toscrape.com/",
    "params": { "mode": "fast", "wait_for": 0, "is_scroll_to_bottom_enabled": false }
  }'

The response is {"data": {...}, "metadata": {"request_id": "...", "screenshot": null}}. mode defaults to "fast", which the docs describe as a mode that "sacrifices some depth of analysis for speed"; "standard" is the one that "ensures a thorough response that may take slightly longer." No latency figures are published for either, which is fair, because they would depend on the page.

I can measure one component of it. Five unauthenticated POSTs to https://api.agentql.com/v1/query-data from this host returned HTTP 401 in 715, 727, 731, 780 and 1,171 ms, median 731 ms, with the TLS handshake alone taking 456 to 899 ms. That is a rejection, not a query, so read it as a floor on per-call latency from this network rather than as AgentQL's performance. Real calls add page fetch and model inference on top.

Now the comparison that makes the floor concrete. Resolving locators inside the page, 50 warm iterations each over the same twenty cards:

1.83 ms against a 731 ms floor is a factor of roughly 400, and the floor is the optimistic end. In a loop that touches one page per iteration, a per-page semantic query is not a small constant, it is the dominant term. Two published limits bound it harder than latency does: the Starter tier allows 10 API calls per minute and Professional allows 50. Fifty calls a minute is a hard ceiling of 3,000 pages an hour no matter how many workers you run, so a 100,000-page crawl needs at minimum 2,000 minutes, about 33 hours, of rate-limited query time alone.

Listed on agentql.com/pricing on 9 October 2026, in USD:

One arithmetic walk, mine not theirs, assuming one query per page: 100,000 pages on Professional is 10,000 included calls plus 90,000 overage calls at $0.015, so $1,350 plus the $99 subscription, $1,449 for the month. On Starter the same crawl is 50 free calls plus 99,950 at $0.02, which is $1,999, so the $99 tier pays for itself somewhere around 6,600 pages.

Two caveats that matter more than the arithmetic. First, the pricing page does not define what counts as one API call for a list query, so whether products[] returning twenty rows bills as one call or twenty is not something I can tell you from published material; the only per-item billing AgentQL documents is for documents, where "the query_document function consumes 1 API call per image...and 1 API call for each page within a PDF." Ask before you model it. Second, remote browser hours are billed separately from calls, so if you use AgentQL's hosted browser (POST /v1/tetra/sessions, which returns a cdp_url like wss://[session_id].tetra.agentql.com) you have two meters running.

Playwright's selector cost, for completeness, is $0.00 and 1.8 ms. The cost of Playwright selectors is engineer time after a redesign, and that is a real number, just not one on an invoice.

Here is the architecture that makes the economics work, and it is not in either project's docs.

A site does not have 100,000 layouts. It has two or three page templates and 100,000 URLs. If you query semantically once per URL, you pay 100,000 times for three answers. So resolve semantically on a cache miss, derive a cheap local selector from whatever came back, and reuse that selector until it stops matching.

The hinge is get_by_prompt() returning a Playwright Locator. AgentQL's Page reference lists query_elements, query_data, get_by_prompt, wait_for_page_ready_state and enable_stealth_mode, and none of them exposes the CSS or XPath that AgentQL resolved internally. So derive one yourself from the element the Locator points at:

DERIVE = r"""el => {
  if (el.id) return '#' + CSS.escape(el.id);
  for (const a of ['data-testid', 'data-test', 'data-qa', 'itemprop']) {
    const v = el.getAttribute(a);
    if (v) return `[${a}="${v}"]`;
  }
  const cls = [...el.classList].filter(c => !/\d/.test(c) && c.length > 2);
  return el.tagName.toLowerCase() + (cls.length ? '.' + cls.map(CSS.escape).join('.') : '');
}"""


def template_key(page):
    """Cheap DOM fingerprint. Changes when a redesign ships, not when content does."""
    return page.evaluate(
        "() => ['article','section','li','h3','p','span','div']"
        ".map(t => t + ':' + document.querySelectorAll(t).length).join('|')"
    )


def prices(page, cache):
    key = template_key(page)
    hit = cache.get(key)
    if hit:
        loc = page.locator(hit["selector"])
        if loc.count() == hit["n"]:
            return loc.all_inner_texts(), "cache"

    # cache miss: pay for exactly one semantic resolution
    semantic = page.get_by_prompt("the price of each product in the listing")
    if semantic is None:
        raise LookupError(f"semantic query found nothing on template {key}")
    selector = semantic.evaluate(DERIVE)
    loc = page.locator(selector)
    cache[key] = {"selector": selector, "n": loc.count()}
    return loc.all_inner_texts(), "resolved " + selector

I ran that pattern against the fixture, substituting a local locator for get_by_prompt() because the documented return type is the same Locator either way. Four page loads, across the untouched page and the fully redesigned one:

Two semantic resolutions for two template shapes, then free forever. Scale that and the Professional tier's 10,000 included calls stops being a crawl budget and becomes a redesign budget, which is a much easier number to live inside. The fingerprint is deliberately coarse, tag counts rather than a hash of the markup, so that a page with a different number of products still hits the same cache entry while a page with a new wrapper element does not.

Two failure modes to design for. The loc.count() == hit["n"] check is what makes staleness loud; drop it and a selector that now matches nothing returns an empty list that looks like an empty page. And if you key on something content-dependent, cache entries will multiply until every URL has its own, at which point you are paying per page again with extra steps.

Neither tool addresses the problem that arrives before selection: being allowed to load the page at all. AgentQL's remote browser accepts a browser_profile of "light" or "stealth" and a proxy object, and the Python SDK exposes enable_stealth_mode(webgl_vendor, webgl_renderer, nav_user_agent). Playwright has --proxy-server and per-context proxies. Both are fingerprint and routing concerns rather than selector concerns, and we covered the detection side separately in headless browser detection and the proxy wiring in web scraping with Playwright and proxies.

Where the fetch layer interacts with this comparison is the js_scenario idea: if the only reason you need a browser is a click or a scroll before the markup you want exists, you may not need a selector engine in your own process at all. SparkProxy's Scraping API runs the browser and the interaction server-side, at https://scrape.sparkproxy.io/api/v1 with an X-API-Key header:

curl -G "https://scrape.sparkproxy.io/api/v1" \
  -H "X-API-Key: $SPARKPROXY_KEY" \
  --data-urlencode "url=https://www.sparkproxy.io/pricing" \
  --data-urlencode "render_js=true" \
  --data-urlencode "proxy_type=premium" \
  --data-urlencode "format=md" \
  --data-urlencode 'js_scenario=[{"wait":1200},{"click":"button.load-more"},{"wait":800}]'

Four parameter facts worth having straight before you cost it out. render_js is on by default and bills 5 credits; set render_js=false for static HTML and the same request bills 1. js_scenario adds 5 credits, requires render_js=true, and caps at 50 steps. country_code adds 5. format governs content conversion only, one of html, md, mdx, json, screenshot or pdf, so format=json is not a response envelope; json_response=true is the only switch that produces one, carrying job_id, status_code, duration_ms, credits_used and a body field that arrives base64-encoded, which has to be decoded before any marker match runs against it. A batch requires render_js=false and the whole batch bills a single credit. A new account opens with 1,000 free credits, and the credit pricing breakdown has the per-parameter table.

Underneath all of it the routing is a plan, not a meter. Entry pricing for SparkProxy residential reads "Starting from $75/month" on sparkproxy.io, checked 9 October 2026, quoted in USD. Plans are packs rather than per-gigabyte tiers: unlimited bandwidth is included, the pool is 1M+ premium IPs in 80+ countries, rotation is either random or on a 5-minute timer, endpoints speak HTTP, HTTPS and SOCKS5, auth is IP whitelist or user:pass, the port runs at 1 Gbps, and the trial lasts 24 hours without a card. Because the billing unit is the plan and its concurrency rather than traffic consumed, the retry storm that follows somebody else's redesign does not arrive as a bandwidth invoice. Term discounts are 5% at three months, 10% at six and 15% at twelve.

Sources: agentql.com/pricing, docs.agentql.com (query language, under the hood, REST reference, Python Page reference, fast and standard modes, release notes), playwright.dev/docs/locators, the PyPI and npm registries, and the GitHub API, all read 9 October 2026. The agentql.com nameservers resolved to Route 53 and both the marketing site and docs returned 200 on the same date.

Three rules that fall out of the matrix rather than out of preference.

Write role locators first, and pin names only when you must. Both bare-role locators in the battery, get_by_role("button") and get_by_role("listitem"), held their counts through all seven variants including the copy pass. The moment you add name="Add to basket" you have traded structural durability for a content dependency, and content is the cheapest thing on a page to change.

Reach for a semantic query where the field is defined by meaning and the page shape is out of your control. Cross-site extraction is the clearest case: one query against twenty competitor catalogues beats twenty selector sets, and the per-call price is trivially cheaper than twenty maintainers. Polling a handful of known pages on a schedule is the clearest case against it, because you will pay 731 ms and a call for an answer that has not changed since yesterday.

Then cache the resolution, not the result. The measured pattern above turned a per-page cost into a per-template cost, two semantic calls for two layouts. That is the move that makes the Professional tier's 10,000 calls a comfortable allowance instead of a crawl budget.

The last thing to carry, and the reason none of this is really about accuracy: a loud failure is usually cheaper than a quiet wrong match. In the browser-automation layer, loud is the default, and the matrix shows why. A dead locator returns zero, strict mode throws on ambiguity, and get_by_prompt() is documented to hand back None. Those all stop a pipeline. The quiet case is the one to engineer against, and I measured one: article p:nth-of-type(1) matched 40 elements on the untouched page and 20 on v6, and its first match changed from an empty string to the price, because the

it used to land on became a