DataFluxor

Permanently delete one finished retained run from the current authenticated scope before the 30-day retention limit. Refused while active, while its charge is unresolved, or while old raw retry receipts for a legacy synchronous result are still draining. New results use payload-free pointers and can be deleted immediately. A matching retry within 24 hours then reports the result unavailable without executing or charging again; after the receipt expires, the key can start new paid work. This cannot be undone and never refunds a charge.

scraper_run_delete

Edits a research document of a project: give title, document or both. A document you give replaces the whole stored one (target, notes, items and sources), so send every part you want to keep; a title alone leaves the document as it is. The kind cannot change, and evidence the dashboard attached to a brief is kept. Limits are those of research_document_save. Give the revision you read (research_document_get), or leave it out to edit the current version; if the document changed since that revision the call fails with a conflict. Free.

research_document_update

Replaces the tags of one saved keyword: tags is the complete list it should have afterwards (up to 10, each one line of up to 40 characters; [] removes them all), so tags you leave out are removed. Tags are all a saved keyword's edit changes; its keyword, market and saved metrics stay as saved. Give the revision you read, or leave it out to edit the current version; if the keyword changed since that revision the call fails with a conflict (read it again with saved_keyword_get). Free.

saved_keyword_update

Fetches one public URL exactly as served — any content type, binary included — and returns status, final_url, redirects, response_headers, content_type, content_length, last_modified, etag and a bounded prefix of the body (max_bytes, default 65536, at most 1048576; truncated says the body continues). This is the tool for validating data feeds and files (XML, JSON, CSV, XMLTV .xml.gz) that web_scrape cannot read: a body that is itself a gzip file is detected (gzip true); valid files return a decompressed prefix with decompressed_bytes counting the stream. If decoding fails, gzip_error says the body contains compressed bytes instead. Text bodies return as UTF-8 (body_encoding utf8), binary as base64. head true sends HEAD and returns headers only. An HTTP error status is an answer, returned with its status and headers. Credits: 1 per fetch whose server answered (the page-read price); a fetch that never reached a server is not charged. This tool runs synchronously. When retention succeeds, retained.run_id reads the completed answer again for free with scraper_run_get; retained.available false says why it could not be kept. Saved synchronous results can be evicted early when storage is needed. The same idempotency_key never charges twice during its replay window.

url_fetch

Reads one research document of a project, including its notes, items and sources. Free. Read-only.

research_document_get

Reads what is already known about one saved keyword, without searching again: its tags and saved metrics (null is unknown, not zero; metrics_note says what each is), difficulty_estimate (DataFluxor's own estimate from the latest results page observed for it, null when none was), the project's target_domain, the latest observed position of that target (rank), and a page of the observations that project-scoped calls and runs recorded for it (source tool, observed_at, rank_status, target_position, depth_checked, complete, run_id, and per tool the competitor positions or the AI Overview presence and citations). Identify the keyword by saved_keyword_id, or by keyword with country and language (and device, desktop when omitted): the market and device are part of its identity, so the same text saved for another market is another saved keyword. A position is never zero: rank.available is false with a reason when the project has no target domain or nothing has been observed yet, rank_status not_in_results means the target is not in the top depth_checked results (a list that is whole for that length, which can be a little shorter than the depth asked for), and unknown means the list proved no absence (a page could not be fetched, or a result had no site). rank is the newest observation that found the target or established its absence, from any of the four tools; one that could not tell is shown only when there is no other. Metrics are the snapshot saved with the keyword and null when unknown; no search volume or CPC source is connected, so they are never estimated here. Observations are recorded by calls made with a project_id (scraper_run_create with scope project, or project_id on google_serp_scrape, competitor_gap_extractor, serp_volatility_sensor and ai_overview_visibility_tracker). Edit its tags with saved_keyword_update and delete it with saved_keywords_delete; project_rank_report gives the latest rank of every saved keyword of a project at once. Free. Read-only.

saved_keyword_get

Retrieve a retained run. This never executes or charges again. Choose how much with view. status: state, progress counts, timing, billing and retry_after_seconds, without inputs, items or results; poll with this. summary (the default): status plus the inputs and the run's result, bounded to about 16 KB. Lists are cut to their first entries and truncated names each cut by path with returned and total; next_step says how to read the rest. full: the whole record, every item result and the run's result together; it is not bounded and is large for a batch, so prefer the paged detail view. detail: one page of the run. section items (the default) returns the items with each item's own result, limit at a time from cursor; section result returns the run's result with one of its lists paged, chosen by collection (a member name such as pages, a dotted path through objects, or omitted for the largest list). items_page or result_page gives total and next_cursor. A response never carries the items' results and the run's result together. The first page keeps the established header and result shape. Set compact true with an explicit result collection to return only id, state, rows, result_page and next_step from page one, without the repeated run header or result wrapper. Later pages (cursor set) are compact. Read view=status or view=summary once for timing, billing, outcome, resume and project link. With verbosity concise and no view named, the summary view is served and its result is the concise form of the run's tool (response summary: outcome, headline, numbers, caveats, failures, the first rows of each list, omitted, read_more) made from the retained result, which is never run again; the views detail and full are what they say. A crawl run's summary is the crawl summary (response summary: status, coverage, counts, top_findings, the report's site-wide results as they are (robots, sitemaps, host_consistency, entry_redirects, duplicates, near_duplicates) with site_checks_not_run naming any the crawl did not make, omitted, read_more), and its result has three lists to page with collection: pages (every crawled page), findings (one row per problem: url, problem, severity, next_step) and broken_links. While a run is not finished, wait retry_after_seconds before asking again: it follows the estimated wait and execution time, it is not a fixed two seconds. Batch runs settle each item as it completes: an item's result appears only once its credits are settled (see settlement, credits and result_available per item), so a poll never returns unsettled paid work. When a run ends before finishing, outcome (completed, partial, timed_out_partial, failed), settled_credits and settled_items describe what was delivered and charged, unfinished_items lists the rest by index and label, and resume.inputs is the input for a new run over only those items (settled items are not re-acquired or re-charged). A keyword-gap, AI-visibility, index-check or volatility run that reaches its time limit still returns the report over the items it finished (charged only for those), marked partial with partial_reason run_deadline_exceeded; a partial volatility score covers only the keywords that were compared (see its note and keywords_requested). A run that did not finish says why in failure (code, message, and target_status when the target site answered an HTTP status) and next_step says what to do: it never points at a result that does not exist, and a failed run is not charged unless credit_state says so. Items a cancellation stopped are counted in progress.canceled (not failed) and marked stopped_by_cancel; their stored state stays failed. Timing is in seconds and keeps waiting apart from executing: queued_seconds (waiting for a slot), paused_seconds (a long run that stood paused between items so that a shorter one could use its slot: state stays running, queue_reason says so, queue_position and estimated_wait_seconds give the wait for its next turn; absent when it never paused), execution_seconds (without the pause) and wall_seconds; deadline_at is the execution deadline, counted from started_at once the run has started and moved later by up to ten minutes while the run waits for shared Google capacity (while queued it is projected from the estimated wait) (while it waits, see queue_deadline_at, estimated_wait_seconds and estimated_execution_seconds; these are estimates, estimate_basis says whether they rest on recent completed runs). A canceled run has state and outcome canceled and error_code RUN_CANCELED; what it settled before the cancellation stays delivered and charged.

scraper_run_get

Harvests autocomplete suggestions from Google using alphabet & question matrix expansion. Returns suggestions that contain all of the seed's words as whole words (a plain plural counts; case and accents are ignored, so a seed typed with accents matches completions without them); completions that keep the topic in another form (a seed word in another word form such as scraper for scraping, matched by spelling rules and so approximate, or a different number or version) are listed separately in related_suggestions with match near. Check coverage (full, sparse or none) and note: new or rare topics often have sparse autocomplete data, and an empty list is not an error. At most 500 suggestions are returned: when Google had more on topic, truncated is true and total_before_cap says how many; the 500 kept are the best-ranked completions of every expansion query, not the alphabetical start of the list. Suggestions are listed in Google's own completion order (the seed's direct completions first), a relevance heuristic, not search volume; each carries a category from its own wording (question, comparison, preposition) or else the expansion that found it (seed, alphabet, modifier, recursive). Credits: 1 per live call, 0 when served from cache. demand_signal is DataFluxor's own relative estimate of how much the seed is searched in this market (index 0-100, band none, low, medium or high, and the autocomplete signals it rests on). It is for comparing keywords and is not a search volume: DataFluxor has no source for Google's search volume or CPC and never reports one. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

google_suggest_harvest

Checks whether each URL appears in a Google site: search: a heuristic, not Search Console. Searches run in the Google market named by country and language (default US, English; the same markets and validation as google_serp_scrape, an unsupported market is refused before any charge, and stored pages are never shared between markets), always desktop, first 10 results (the result states method, location, country, language, confidence and a disclaimer that name the market used). Each URL gets verdict observed, not_observed (not seen in that search; not proof it is not indexed) or unknown (is_indexed null, with a reason such as result_urls_hidden, google_challenge or prefix_url_inconclusive: a home or section URL that other indexed pages sit under is listed through those pages, so when only they appear a site: search cannot show whether the URL itself is indexed); checked_at is when the check ran and observed_at when Google's page was fetched (earlier when cached). Credits: 5 per URL checked live, 0 when served from cache; unknown checks are free, and a batch in which every URL is unknown is a normal answer (verdict unknown with the reason on each row, nothing charged); only a row with retry_may_help true failed for a reason a repeat can fix. Verdicts are specific to the market searched: the same URL can be observed in one market and not in another. When the daily live-page allowance or the balance does not cover live pages, cached URLs are still served at no charge and the rest are not checked (error_code DAILY_LIVE_LIMIT or INSUFFICIENT_CREDITS). market_check says whether the country the results are for is confirmed: confirmed (market_evidence.method says by what: page_data or page_footer, Google's own page states it; provider_echo, the search provider states the country it searched), or unconfirmed (nothing states it; the page is returned but never recorded as a rank observation). A page produced for another country is discarded and fetched again; MARKET_MISMATCH means no fetch gave the requested country. A cached Google page is not a new observation of Google: observed_at names when the stored page was fetched, even if this check is retained as a run. Project retention is offered only when project_id appears in the schema. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

google_index_check

Google organic results for 247 countries, each with a default language (most also accept others). Credits: 5 per Google results page fetched live, 0 per page served from cache; live pages also count toward the plan's daily live-page allowance (DAILY_LIVE_LIMIT when used; cached results are still served). A fresh result can take 30-120 seconds. If a call times out, repeat the identical call: the search keeps running server-side and the repeat returns the finished result from cache at no charge, without a second acquisition. For long or batch work, start it with scraper_run_create (tool "serp") and collect it with scraper_run_get. Read requested_depth, results_returned, complete and partial_reason together: fewer results than requested is a whole answer when complete is true (every results page asked for was fetched and Google's pages held fewer than ten organic results each; results_note says so). requested_at is when Google was asked, cache_age_seconds how old a stored copy is, served_at when this response was made; execution_time_ms is how long this request took, and original_execution_time_ms, on a stored copy, how long collecting the page took. When Google answers another query than the keyword ("Showing results for ..."), query_correction and executed_query say so, verified_depth is absent, and a position or absence in the page is not recorded as the keyword's rank; repeat with exact_query true to ask for the keyword as typed (exact_query_applied says whether the source could). verified_depth is the N for which a site that is not in items is proven to be outside Google's top N (often a little less than the depth asked for, because a results page carries eight to ten organic results); when it is absent the list proves no absence. One search has one current observation whatever tool made it: a request is answered from the newest stored page that covers it, and when only a shallower newer one exists the response is the older copy with newer_observation saying so (ask for freshness "fresh" to collect the list again). query_check says whether the page answers the search that was requested (confirmed, or unconfirmed when the source did not name the search, or corrected when Google answered another query, executed_query naming it; a page for another search is never returned). Each item's url_source says how its url was found: result_link (the result's own link), page_data (the page's embedded data), goto_resolved (Google's /goto link asked where it leads, on the site the result displays), matched_source (another block of the page links the same site with the same title) or token_decoded (the link token carried it in the clear); absent when url is empty. market_check says whether the country the results are for is confirmed: confirmed (market_evidence.method says by what: page_data or page_footer, Google's own page states it; provider_echo, the search provider states the country it searched), or unconfirmed (nothing states it; the page is returned but never recorded as a rank observation). A page produced for another country is discarded and fetched again; MARKET_MISMATCH means no fetch gave the requested country. With project_id, only a page fetched for the call is recorded as an observation of the project's saved keywords: a page answered from storage (cache_hit) is not a new observation, and project_link.note says so; freshness "fresh" observes now. Each item's url_source says how its url was found: result_link (the result's own link), page_data (the page's data names it), goto_resolved (the browser session that rendered the page asked Google's redirect link where it leads; the answer is on the displayed site), matched_source or token_decoded; url_error says why when url is empty. keyword_difficulty is DataFluxor's own estimate of how hard the search is to rank for (score 0-100, band, confidence, the signals it rests on), computed from this results page; it is not a backlink-based or Google figure, and DataFluxor reports no search volume or CPC because it has no source for them. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

google_serp_scrape

Lists the projects of the organization this connection is signed in to (account_info shows which): each project's ID, name, creation time, revision, target_domain (the site its positions are computed for; null when none is attached) and how many saved keywords and research documents it holds. Use it to find the project_id that the saved keyword, research and project-scoped run tools need; never guess an ID. project_create makes a project, project_set_site sets its target, project_rename renames it and project_delete deletes it. 1-100 per page, oldest first; follow next_after. Free. Read-only.

projects_list

Lists the research documents of a project (keyword lists, content briefs, competitor sets, prompt sets and reports; the Research library), 1-100 per page. Follow next_cursor. Free. Read-only.

research_documents_list

Lists the keywords saved in a project of your workspace (the Saved keywords page), 1-100 per page, newest first unless sorted. Free; nothing is fetched from Google. Read-only.

saved_keywords_list

List retained runs for one tool in the current authenticated scope, newest first, as run-level summaries: state, outcome, what the run covers (summary), project_id, progress counts by item state, timing and billing. It returns no inputs, item rows or results; read those with scraper_run_get. Follow next_cursor.

scraper_run_list

Lists every supported search market: its two-letter country code (the country argument of the search tools) and the language Google serves there, plus each market's supported devices (markets[].devices) and the service-wide device capabilities. A service-wide mobile capability does not imply every market supports mobile. The concise answer lists the first 25 markets and says how many exist; pass verbosity full for every market. Use it to pick a valid country before searching instead of guessing: results differ per country, and the tools refuse a market that is not listed. Free. Read-only.

serp_markets

Extracts HTML metadata, OpenGraph, Twitter Cards, headings, word count, links, language (lang, hreflang), title and description lengths, image alt coverage (images: with_alt, empty_alt for decorative images, missing_alt) and JSON-LD (json_ld: blocks, how many parse as JSON, their @type values, and rich_results: each Product, Article, BreadcrumbList, Organization, LocalBusiness, Recipe, Event and VideoObject entity checked against the properties Google documents as required and recommended, with meets_required, missing_required and missing_recommended; FAQPage is reported as retired because Google no longer shows the FAQ rich result; JSON-LD only, the Schema.org vocabulary is not checked, and meeting the requirements makes a page eligible, never certain of a rich result) from a URL. url is the URL you asked for; final_url is where the request ended, with final_status, the redirect chain (status, url, location per hop) and redirect_host_changed, so the metadata can be tied to the HTTP response it came from. response_headers lists the content, caching, indexing and transport-security headers (never cookies or credentials); response_header_repeats names any of them the server sent more than once, with the count, values and what the repeat means, and response_header_clips names any whose value was cut at the reported bound, with the length of the whole value. With render true the page is also loaded once in headless Chrome (https pages only) and the result adds rendered: the page as served compared with the page after JavaScript ran (title, meta_description, canonical, robots_meta and h1 raw and rendered with a status of same, javascript_only, changed, removed or absent; word_count, headings and link counts; javascript_only and changed_by_javascript name what depends on scripts) and rendered.lab, the lab metrics of that one load (time to first byte, first and largest contentful paint, DOMContentLoaded and load times, cumulative layout shift, request count, transfer bytes): lab data from DataFluxor's servers, one run, not Core Web Vitals field data and not a Lighthouse score. Credits: 1 per page; 5 with render when the page was rendered (a page that could not be rendered, rendered.status unavailable, is charged 1). The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

html_metadata_extractor

Checks many public URLs in one call (1-100): for each, status, ok, final_url, redirects (each hop's status, URL and Location, capped at 10), content_type, content_length (the server's Content-Length header; with content_encoding set, content_length_compressed is true and it counts compressed bytes, often of an empty HEAD body, so it is not the page's size: url_fetch measures that), method, last_modified and etag, or an error word (target_refused, timeout, fetch_failed). HEAD is tried first with a headers-only GET fallback, redirects are followed, and one bad URL never fails the probe — use it to triage a candidate list (feed URLs, sitemaps, downloads) before fetching bodies with url_fetch. Credits: 1 per URL whose server answered; URLs that never answered are free, and answered counts them. This tool runs synchronously. When retention succeeds, retained.run_id reads the completed answer again for free with scraper_run_get; retained.available false says why it could not be kept. Saved synchronous results can be evicted early when storage is needed. The same idempotency_key never charges twice during its replay window.

url_probe

Reports where a project's target domain ranks for each of its saved keywords, from what has already been observed: it searches and fetches nothing. One row per saved keyword, 50 a page (limit up to 200; follow next_cursor): keyword, country, language, device, rank_status, position (null when there is none, never 0), url, depth_checked, observed_at, source and a reason when there is no position. Each row says what the rank rests on: stability, best_position, worst_position, median_position, absent_from_top, seen_in ("2 of 3"), window (the 24 hours of observations up to the newest one; from and to say when), observation_ids, previous_position and position_change (against the newest position before the window; positive is up) and, without a position now, last_known_position and last_known_at. For the whole project, whatever the page or filter: target_domain, a one-sentence summary, totals per status and changes (improved, declined, unchanged, no_earlier_position, dropped_out). rank_status is ranked; not_in_results (complete observations did not contain the site); unstable (the observations of that window disagree: found in some and not in others, or positions more than 3 apart; position is null, the range is in best_position, worst_position and absent_from_top); unknown (absence not established); no_target (use project_set_site); not_measured (no observation measured the target); or not_observed (a call with this project_id records observations). Positions come from public results; they are not Google Search Console data. Each row has difficulty_estimate (DataFluxor's own estimate from the latest results page observed for the keyword; null when none); there is no search volume or CPC, which DataFluxor has no source for (metrics_note). rank_status filters the rows. Free. Read-only.

project_rank_report

Renames a project. Only the name changes: the project's ID, sites, saved keywords, rank history and research documents stay as they are. Needs an owner or admin of the organization (an organization API key acts as one; an OAuth connection acts in the signed-in person's role). Give the revision you read (projects_list), or leave it out to rename the current version; if the project changed since that revision the call fails with a conflict and renames nothing. The result gives the new name, the previous name and the new revision. Repeating the call with the same name changes nothing further. Free.

project_rename

First call for a keyword set: unless the same search was stored in the last 24 hours, it only saves a baseline and returns no score; call again later (hours to days apart is most meaningful) to measure movement. Compares fresh SERPs of a keyword set with the previous observation of the same keywords, country and language to score rank turbulence. Each keyword is a live observation of the top 20 (up to 2 Google pages, 5 credits each). The score (0-10) is the share of expected organic clicks that changed hands, weighting each result by its position (position 1 counts about 40 times position 20), so turnover in positions 11-20 barely registers while a change at the top of the page does; levels are LOW below 3, MODERATE 3-5.4, HIGH 5.5-7.9 and EXTREME 8 or more, and every measured report states its method in score_method. The first observation only saves a baseline: it costs 5 credits per live Google page saved (at most 10 per keyword), counts toward the daily live-page allowance and carries NO volatility judgement (baseline_status insufficient_history, volatility_available false, overall_volatility_score, level and algorithm_update_likely null, plus a note); comparison starts with the next check, which measures real movement. A keyword with no saved baseline is instead compared at once with the newest stored observation of the same search from the last 24 hours, made by any tool (its baseline_source is stored_observation, previous_observed_at says when); such a keyword is billed like a first observation, 5 credits per live page. algorithm_update_likely is a heuristic, set only when the overall score is 5.5 or more over at least 3 compared keywords. Each keyword is compared over the depth both observations cover (compared_depth); every listed change has status new, dropped or moved, a null position where the observation does not hold the domain, and movement (previous minus current, positive = up) only when moved. new and dropped mean entering or leaving the compared positions, not proof of a wider ranking change; confidence low with comparison_limits tail_only marks entries and exits found only below position 8, which Google's later pages vary between sessions. A baseline that shares at most one first-page site with the current page is another page (comparison_limits baseline_mismatch): that keyword is left out of the score and billed as a first check; one observed less than an hour earlier is flagged baseline_recent (low confidence). If every keyword is left out because Google corrected it, the report says so per keyword and in query_corrected/note; no comparison is delivered, the call costs 0 credits and consumes 0 daily live-page allowance, even though live_pages reports pages actually fetched. market_check says whether the country the results are for is confirmed: confirmed (market_evidence.method says by what: page_data or page_footer, Google's own page states it; provider_echo, the search provider states the country it searched), or unconfirmed (nothing states it; the page is returned but never recorded as a rank observation). A page produced for another country is discarded and fetched again; MARKET_MISMATCH means no fetch gave the requested country. This tool always fetches live, because it compares now with its saved baseline: it takes no freshness or max_age_seconds. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

serp_volatility_sensor

Saves 1-100 keywords to a project of your workspace. A keyword already saved for the same market and device is skipped and counted in duplicates, so repeating a call is safe. Limits: 1,000 saved keywords per project and 5,000 per organization; beyond them the call fails with keyword_limit and nothing partial is hidden. Free; nothing is fetched from Google.

saved_keywords_save

Creates a research document in a project. Limits: 200 documents per project and 1,000 per organization; kind is keyword_list, content_brief, competitor_set, prompt_set or report; title 1-120 characters; document.items up to 200 lines (competitor_set 10, prompt_set 50); notes up to 32 KiB. Each call creates a new document, so do not repeat it to retry a call that succeeded. Free. This tool only creates; use research_document_update to edit one and research_document_delete to delete one.

research_document_save

Scrapes one public webpage you already have the URL of and returns its content as Markdown: url, final_url, status, title, markdown, outcome (read, no_content, no_main_content, needs_javascript, image_only or access_gate, with reason), the page's own published_at/updated_at when it declares them, and browser (what the browser did). browser=auto (default) reads the page directly and opens it in an isolated headless browser only when the direct read gets no readable content, a JavaScript-only page or an access challenge, or the site refuses it (HTTP 403, 429 or 503); never reads directly only; always uses the browser only (https pages on port 443). include_html adds the browser's rendered HTML. Credits: 1 for a direct read, 5 when the browser read the page; an access challenge, consent or sign-in page is labelled and costs nothing; a failed read costs nothing. auto and always reserve 5 credits and settle at what was used. It does not search: to find pages for a query use web_search; for one file or feed exactly as served (XML, JSON, CSV, gzip) use url_fetch; for the status of many URLs use url_probe; for SEO tags of a page use html_metadata_extractor; for a whole site use site_seo_crawler. The result is returned here only and is not kept as a run. The same idempotency_key never charges twice.

web_scrape

Attaches a site to a project and makes it the project's target: the domain its keyword positions are computed for. site is a domain or URL such as example.com or https://www.example.com/; only its host is kept as typed, and www.example.com and example.com are two attachments, but the positions computed for the target do not depend on which was typed: a result on the site with or without www, or on a host under it, is the site's (blog.example.com counts for example.com; notexample.com and example.com.evil.test do not). A site already attached is not attached twice; sites attached earlier stay attached, only the target changes. Observations recorded before a site was attached carry no position, and those recorded for a previous target are kept but not used for the new one: a saved keyword shows a position after a call with this project_id observes it again. Repeating the call is safe. Free; nothing is fetched from Google.

project_set_site

What changed since the last crawl of the same site. Compares a finished retained crawl run with the previous finished crawl run of the same site (the start address's host, www. ignored) in the same account, or with against_run_id, and returns: new_pages, not_found_in_current_crawl (URLs the current crawl did not reach: removed, no longer linked or beyond max_pages, never proof of deletion), status_changes, field_changes (title, meta_description, h1, canonical, noindex, for pages audited as HTML in both; a change that is only in numbers, such as a price in a description, is grouped in volatile_field_changes unless include_volatile is true, and ignore_fields leaves fields out), findings (every problem identified by page, rule and field and classified new, persistent, changed or resolved, with by_rule counts, not_rechecked for problems on pages that were not measured again, and rules_not_compared naming the rules left out and why), finding_changes (the same per page) and finding_totals. Each list is cut to 50 entries with its total. A page the target throttled, refused or that failed to load in either crawl is counted in pages_not_comparable and nothing is claimed about it; its problems are never reported as resolved. comparison says whether the two crawls covered the same pages (page_set_comparable, with reasons) and which rules versions they were made with: when they did not, new and missing pages may only reflect where each crawl stopped, and the duplicate-content rules are not compared. caveats say it in words. Only crawls started as retained runs are kept, for 30 days; a direct site_seo_crawler call is kept as a run too (its retained.run_id). Reads stored evidence only: it fetches nothing and costs no credits. At the scan limit it reports an incomplete search and a before cursor for scraper_run_list.

site_crawl_changes

Which pages that were crawled for you link to a domain or URL. Searches the pages of your account's newest retained crawl of each site (up to 10 sites, 30-day retention) for links to target and returns the linking pages (source_url, the links_to found on it, the run and time it was crawled), a count by linking host and pages_with_cut_links, the number of pages whose external links may be incomplete (at most 20 distinct URLs are kept, none over 300 bytes; older crawls may be uncertain). target is a bare domain (example.com: the domain and its subdomains) or a full URL (that address only; internal links to a crawled page come from found_on, at most 5 per page; internal_sources_truncated says when more were found). This is not an index of the web and not a backlink count: it covers only pages your own crawls fetched, and another account's crawls are never searched or shown. Reads stored evidence only: it fetches nothing and costs no credits. At the scan limit it reports an incomplete search and a before cursor for scraper_run_list.

site_link_sources

Explicitly start a retained background scraper run that may contact public sites and spend plan credits. Requires idempotency_key and verified organization/project or legacy credential scope. The same key retrieves the original run, including failed or interrupted work, and never re-executes or re-charges it; never automatically retry with a new key. To finish a run that timed out or stopped partway, submit the resume.inputs from scraper_run_get as a new run with a new key. A synchronous scraper tool call is also kept as a completed run (its answer carries retained.run_id), so scraper_run_create is for work that should run in the background, not for keeping a result. Run results are retained for 30 days within bounded server capacity; kept synchronous results are the first to make room. For tool ai-visibility with project scope, the AI prompt, answer text and source evidence also enter this organization's AI history until the project is deleted; deleting the project queues their removal. Organization and credential scope do not retain that project history.

scraper_run_create

Crawls a website and audits technical SEO health: HTTP status, titles, H1s, meta descriptions, canonicals, internal/external links. Follows robots.txt pacing. A page the target throttles (HTTP 429, or 503 with Retry-After) is retried up to twice within a bounded wait, the crawl slows down, and a page still throttled is reported as rate limited, not as a broken link. Redirect (3xx) URLs are recorded as redirects and not audited as pages; 401/403/451 pages are reported as access refused, not broken; noindex pages skip the canonical check. A start address that redirects to the site's www or bare form is crawled where it lands (start_redirect and the start_redirected note). A linked URL that is not a web page (a download, image or document) is not read and is listed in the non_html_links note, not as a failure, and does not consume the max_pages budget (it is still fetched, so a dead download link is still reported; total fetches stay bounded at three times max_pages). status_reasons says why a crawl did not cover every page it found: deadline_reached, cancelled, pages_not_collected, rate_limited, access_refused, max_pages_reached (alone it leaves the status completed). Read pages_html_audited (audited as HTML), pages_redirected, pages_rate_limited, pages_access_refused and pages_failed (real failures) separately: pages_crawled counts every URL that answered, whether or not it could be audited. pages lists every attempted URL; failed means no HTTP response, unreadable means a response arrived but could not be audited. coverage and site_checks explain skipped or partial checks, and retry lists URLs to audit again with urls. Per-page findings and crawl notes are reported apart from issues. Each audited page also carries content (lang, hreflang, title and description lengths, word_count, json_ld blocks and whether they parse with their rich_results, images by alt attribute, links to anchors, outbound_links: up to 20 distinct external URLs it links to) and found_on (crawled pages that link to it); broken_links lists each broken URL with the pages linking to it. A redirect states redirect_host_changed and redirect_not_followed (other_host, robots_disallowed, redirect_limit) with the full chain. Site-wide, when the crawl ends: robots (status, Sitemap lines), sitemaps (URLs listed versus crawled; a listed URL that was not fetched was not reached within max_pages, which is not evidence that it is unreachable or not indexed), host_consistency (does the www/non-www form redirect here), entry_redirects (each other address of the site, http or https and with or without www, followed to its end: multi_hop_redirect when it needs two or more redirects, which a crawl of the final address cannot see) and start_page_headers (never cookies or credentials). duplicates compares titles, meta descriptions and H1 headings across the crawled pages and gives each a result: none_found, found (with the groups) or not_checked. Length and thin-content findings are this audit's heuristics and say their thresholds (a title is recommended at 30 to 60 characters); slow_page_response is raised from the time the crawler's own request took (one sample from DataFluxor's servers, not a Core Web Vitals measurement), redirect_chain for a URL that needs two or more redirects, and a header the server sent twice is reported for the start page as start_page_header_repeats and duplicated_response_header in start_page_findings (a repeated X-Frame-Options is invalid; a repeated Content-Security-Policy is allowed), and a start page header value longer than the 512-byte bound is cut in start_page_headers and named with its whole length in start_page_header_clips; json_ld checks each parsed entity of the common rich-result types (Product, Article, BreadcrumbList, Organization, LocalBusiness, Recipe, Event, VideoObject) against the properties Google documents as required and recommended (rich_results; JSON-LD only, the Schema.org vocabulary is not checked, and eligibility is not a guarantee), raised as the findings rich_result_missing_required, rich_result_missing_recommended and rich_result_retired (FAQPage, a rich result Google no longer shows); a link to Cloudflare's /cdn-cgi/l/email-protection is an obfuscated email address and is not fetched. With urls (up to 100 URLs on the host of url), the crawler audits only those URLs once, without following links or running site-wide checks; coverage then describes those URLs only. Size: a large crawl report is 100 to 200 KB, so this tool answers with a summary of it (response summary: status, coverage with what the findings do and do not cover, counts, top_findings, the report's site-wide results as they are (robots, sitemaps, host_consistency, entry_redirects, duplicates, near_duplicates; site_checks_not_run names any the crawl did not make), omitted, retained.run_id and read_more) and keeps the whole report for 30 days; read every page, every problem row (url, problem, severity, next_step) and the broken links a page at a time with scraper_run_get and the arguments in read_more (view detail, section result, collection pages, findings or broken_links; follow result_page.next_cursor), or everything at once with view full. Reading a kept crawl never crawls again or charges. Credits: 1 per auditable HTML page (pages_html_audited); redirected, throttled, refused, failed, HTTP-error and non-HTML URLs are free. max_pages or the number of urls is reserved up front and settles to pages audited; robots, sitemap, host and entry-address requests are not charged. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

site_seo_crawler

Searches the web for a query and returns agent-ready JSON: ranked results (position is Google's rank, display_rank the order shown) with the content of each result page. content controls what is read: none returns the result list only (no page fetched — the discovery step of a staged search); limit runs to 30, and above 10 the search fetches deeper Google pages; excerpt (default) returns a short clean excerpt of each page; full returns each page as Markdown (capped per result and by the whole-answer budget). Excerpts are made after boilerplate comes out (menus, link rails, repeated promos, furniture) and prefer the passages that answer the query, so page chrome cannot spend the excerpt budget; max_chars_per_result narrows the cap and max_total_bytes (default 65536) bounds the whole answer, cuts marked truncated and expandable (read that page whole with web_scrape). Discovery can be steered without another search: include_domains keeps only the listed sites (a domain covers its subdomains), exclude_domains drops its sites and wins over the allow list, and official_domains marks the sites you declare official (official_match, official_basis caller_declared — your declaration, never verified); prefer_official presents those first while position stays Google's rank (presentation and applied_filters say what was applied; filtering selects from the results already collected and never searches again to refill). prefer_domains selects results on those sites into the returned set first, positions unchanged; file_types keeps only results whose URL ends in one of the extensions (filtered_results counts the rest); published_after drops read results older than the date their page declares (stale_results counts them; undated pages are kept, and dropped pages were read and are charged); excluded_results counts results exclude_domains dropped. query_check and market_check say how the query and country were confirmed (executed_query and query_correction name a corrected query), and matched_terms names the executed query's terms found in each title or snippet. Each result states its evidence: evidence_status fetched_page (the page itself was read), snippet_only (only Google's snippet backs it — not verified page text) or no_evidence; content_status says what a read found: read (its main content), no_content (no readable text), no_main_content (only navigation or page furniture), needs_javascript (main content may need JavaScript or may be unavailable), image_only (images but no text), access_gate (a consent, sign-in or challenge screen), not_selected, no_url or failed; a page that fails to fetch is failed with a reason and HTTP status, fetched exactly once and never retried silently, and names a suggested_alternative from the same results page. Dates are kept apart: serp_collected_at (requested_at) is when Google was asked, page_retrieved_at when a result page was fetched, and published_at/updated_at only what the page itself declares (with their sources; absent stays unknown). timing splits the measured serp_ms, page_read_wall_ms, page_fetch_sum_ms and page_extract_sum_ms (the sums exceed the wall time when reads overlapped). The synchronous answer is whole when it returns; for result-first work call content none or a small max_pages_to_read, choose, then read the chosen pages with web_scrape (or run the search retained with scraper_run_create, tool search, and poll it). Result pages are read as static HTML without running scripts, so an access gate or script-only page stays access_gate, failed, needs_javascript or no_content rather than being retried or bypassed; the rendered comparison, where the service enables it, is html_metadata_extractor with render. Snippets are Google's own text as collected at serp_collected_at, so a relative age inside one ("7 hours ago") is Google's wording anchored at that collection moment, never a verified publication or release date. The results page itself follows the shared cache controls: freshness standard may answer from a stored page inside its window (0 credits, serp_cache_hit and the collection time state it; a cache answer is never guaranteed), max_age_seconds narrows the oldest stored page that may answer, and freshness fresh always fetches live; result pages are always fetched for this call. It composes google_serp_scrape and web_scrape's direct read server-side and is offered when the account holds both; each remains usable on its own. Credits: the Google results pages fetched (5 live, 0 from cache, per page) plus 1 per result page whose main content was read (content_status read; each result's credits states its own), at most max_pages_to_read of them; pages that fail or hold no main content are free, content none costs only the results pages, and cost_estimate states both maxima before execution (estimate_only returns them without running or charging anything). A read credit pays for fetching the page even when max_total_bytes afterwards cuts its body in this answer — possibly to empty — and such a result keeps content_status read with truncated and expandable set so the cut is visible, never silent. Documentation-looking URLs carry documentation_version_hint: literal version or rolling URL labels, their source and unknown where no label is found. With documentation_version it compares the label to the requested release, but URL labels may name an API or another component and never establish compatibility. No extra search or page read is made. The result is returned here and may also be kept for up to 30 days as a completed run: retained.run_id reads it again for free with scraper_run_get (retained.available false says why it was not kept). Saved synchronous results can be evicted earlier when storage is needed; use scraper_run_create for background work. If the call would outlast the connection (many items, deep or fresh SERPs) or the platform has no free capacity, it is not failed: the result is an accepted answer (accepted true, run_id, state, next_step) and the work runs as a saved run; ask scraper_run_get about run_id (view status) as often as retry_after_seconds says. A batch tool's run is charged item by item as each item finishes (failed items are free); any other run once, when it completes. The same idempotency_key prevents a second charge during its retry window; a later new call may be charged.

web_search