Alterlab

Fetch one URL and return its content as clean markdown, text, HTML, or JSON. Use when a normal fetch returns 403/429, a bot-protection challenge page, a CAPTCHA, or an empty JavaScript shell. Website challenges and JavaScript-heavy pages are handled automatically by a 5-tier system that starts at the cheapest tier that works and escalates only when needed. Returns markdown by default, ready for LLM context. Supports GET and POST via method, structured extraction via extraction_schema or extraction_prompt, and cost caps via cost_controls. Supports browser actions via actions, plus screenshot and generate_pdf; the response includes action_results, one entry per action with index, type, success, error, result (evaluate) and screenshot_url (screenshot actions). When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Extract structured data (prices, product info, contact details, custom fields) as JSON from HTML, text or markdown you already hold. Use when you have content and need specific fields. Does not fetch a URL: to fetch and extract in one step, use alterlab_scrape with extraction_schema. LLM extraction (extraction_prompt, extraction_schema) requires your own LLM API key (OpenAI, Anthropic, OpenRouter, etc.) added in the dashboard BYOK settings; without one it fails with byok_key_required. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Capture a full-page PNG screenshot of one URL, an image rather than text content. Use when a normal fetch returns 403/429, a bot-protection challenge page, a CAPTCHA, or an empty JavaScript shell. Works on anti-bot-protected sites, rendered in a real headless browser. Use wait_for to wait for an element and wait_until to control load timing. Pass actions (for example dismiss_consent or evaluate) to prepare the page; the screenshot is captured after they run and action_results is returned. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Crawl a whole website and return the content of every page, for RAG, indexing or site-wide export. Use when you need many pages from one domain; for one URL use alterlab_scrape, for a URL list only use alterlab_map. Works on JavaScript-heavy and protected sites, with anti-bot handling on every page. Returns a crawl_id immediately; results are available from GET /api/v1/crawl/{crawl_id}. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Search the web and read the results in one call. Returns a unified, vendor-neutral result list (URLs, titles, snippets) with each result page as concise markdown and a per-result content_status (ok, partial, blocked, timeout, dead_origin, pending; only fetched pages are billed). Use when you have a question or topic but no URL yet; for one known URL use alterlab_scrape. Set scrape_results=false for the result list only (cheapest); concise=false returns full-length content; mode trades latency for coverage. Use domain to restrict to one site and time_range to filter by recency. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Answer a hard question with a cited report or structured JSON by running a budgeted research job: it plans searches, reads many sources, follows leads and attaches a citation to every claim. Use when one search is not enough; for a quick lookup use alterlab_search. Runs on your own LLM key (BYOK); without one it returns byok_key_required and charges nothing. Set effort (lite, standard, deep, exhaustive) and max_cost_microcents to cap spend. The call waits within the tool time budget; if the job is still running it returns the job id and status, and you call again with job_id to fetch it. Returns status, cost, coverage, warnings and the result.

List every URL on a site via sitemap parsing and link extraction, without fetching page content. Use before alterlab_crawl or alterlab_batch to choose pages; to read the content itself use alterlab_crawl. Works on JavaScript-heavy and protected sites. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Scrape 2-20 URLs in parallel and get every result back in one synchronous call, no polling required. Use when a normal fetch returns 403/429, a bot-protection challenge page, a CAPTCHA, or an empty JavaScript shell. Failed URLs report their error; successful ones return content. For 20+ URLs use alterlab_batch. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Start an asynchronous batch job for a large URL set (up to 100 per call) and poll for results later. Use when a normal fetch returns 403/429, a bot-protection challenge page, a CAPTCHA, or an empty JavaScript shell. Each URL can have its own mode, formats and extraction_schema. Returns a batch_id immediately; results are available from GET /api/v1/batch/{batch_id}. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Estimate the credit cost of scraping a URL before you run it. Use when cost matters or before a large job; no credits are charged. Returns the predicted tier, estimated cost and confidence. Full machine-readable price list: GET https://alterlab.io/api/v1/pricing (public, no auth). When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Get AlterLab's machine-readable price list: per-tier cost, bring-your-own-proxy discount, cache-hit discount, add-ons, search and SERP prices, and the free allowance. Use when deciding whether AlterLab fits a budget, before any account exists. Free and keyless; nothing is scraped or charged. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

无需输入参数。

Search aggregated news headlines from curated public sources: headline, URL, source, published time, author, image, short snippet and category. Use to find what is being reported on a topic. Served from a cache that refreshes about every 15 minutes, so a call never triggers a fetch; free and keyless, no credits are spent. Returns metadata only, not article text: to read an article, call alterlab_scrape on its URL. Cite results as 'News via AlterLab'.

Fan out a seed keyword across autocomplete (seed + a-z + who/what/how/why/best/vs), People Also Ask and related searches, and get deduplicated ideas, each with source, question flag, intent (question, commercial, navigational, informational) and a 0-1 relevance score. volume is always null: there is no search-volume data, and the score is relevance (frequency across sources and positions), not volume. Billed per successful call; set quote_only=true to get the price first without running anything. Results are cached 7 days per seed, country and language and a cache hit costs half the quote.

Run prompts against AI answer engines through their public, logged-out interfaces and get, per engine and run, the answer text, whether the brand is mentioned and its position, competitors mentioned, cited URLs and domains and a sentiment label, plus per-prompt mention rate, share of voice and citation share with the sample size. Answers vary run to run, so set runs_per_prompt. Billed per successful engine answer only; an engine that needs login returns engine_unavailable_logged_out and is not billed. Use action=quote (or action=check with quote_only=true) to get the price first, and set hard_cap_microcents to refuse any run quoted above it. action=check (default) runs the check; action=status and action=results read a past run by run_id.

Tell AlterLab when something is hard, or what would make it better. Call this when something blocks you, a result is wrong, or a step is confusing, slow or priced unexpectedly, and also to send a suggestion (category `suggestion`, ideas welcome even when nothing is broken). Describe what you tried, what happened and what you expected. Send sanitized setup or API friction automatically; ask the user first before sending suggestions or anything quoting their data or URLs. Do not include secrets, API keys, passwords or customer data; use a job_id or hostname instead of page content. Works without an API key (rate limited per IP); with a key the report also appears as a ticket in your user's AlterLab dashboard (the response carries its ticket_ref) and similar reports are grouped. Returns a cluster_key and a status_url to check progress. For billing, account or data problems that need a human, use `alterlab_support_ticket` instead. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Open a support ticket in your user's AlterLab account when they need a human: a billing, account or data problem. Do not use it for scrape friction, blocks or ideas; use `alterlab_feedback` for those. Ask the user first: a ticket reaches a human and emails them. Requires an API key. Describe the problem in `body`; do not include secrets, API keys, passwords or customer data. The user gets the usual confirmation email and the ticket appears in their dashboard. Limited to 3 open tickets and 5 per day per key; when over the limit the error points to the open ticket. Returns ticket_id, ticket_ref and status. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Create an AlterLab account and API key for your user. Use only when no ALTERLAB_API_KEY exists yet; skip it if a key is already configured. Signup is on behalf of your user (agent signup with human approval). Nothing is created until the human approves: they get an email (and you get a verification_url and user_code to show them) describing what the agent can do. After approval you receive a scoped API key labeled with agent_name, with a default daily spend cap, revocable from the dashboard. No extra free credit is granted; the usual welcome rules apply to the human's account. If the human has not approved yet, the result contains the signup_id, verification_url and user_code; poll GET /api/v1/agent/signup/{signup_id} or call this tool again. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Create one scoped, spend-capped API key (ALTERLAB_API_KEY) for the SDK and REST API on this machine. Works only when the user ticked "Also create an API key for this machine" on the OAuth approval screen, so no second approval is needed. Skip it if a key is already configured. The key is labeled with your client name, carries the same read/write permissions and daily spend cap as this connection (never billing), and is revocable from the dashboard. The plaintext is returned once: store it in the environment immediately without printing it. A repeat call returns key metadata only. If it fails with a permission error, the box was not ticked: use alterlab_create_account instead. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

无需输入参数。

Use this to look up how to do something with AlterLab (API parameters, SDKs, MCP setup, pricing, error codes, migration from Firecrawl/ScrapingBee/Apify) or to find a guide for scraping a specific site. Searches the docs guides and API reference by default (blog posts only when you pass type=blog); the answer field gives the first actionable step from the best guide with a link. Free: needs no API key and never uses credits. Returns the best matches as title, short snippet, url and markdown_url; pass a url to read_alterlab_page to read the full page as markdown. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Use this after search_alterlab to read the full text of one AlterLab page as markdown, so you can follow the documented steps instead of guessing. Pass the url of a search result. Only pages on alterlab.io that search_alterlab can return are readable. Free: needs no API key and never uses credits. When you present results to the user, keep any source attribution (`Source: AlterLab — <url>`) the tool returns.

Query a search engine and get structured results: organic listings, ads and related data, from Google, Bing or DuckDuckGo. Use action=search (default) to run a query, or action=history to read earlier SERP queries for your account. Prefer alterlab_search when you also want each result page scraped. Search runs spend credits at the SERP rate.

Look up a job by id. action=status (default) returns its status and result once finished; set wait (seconds) to hold the request until the job reaches a terminal status. action=explain returns the ordered per-stage timing breakdown, useful when a job was slow or failed. Job ids come from async scrape, crawl, batch and SERP responses.

Read account credit data. action=balance (default) returns the current credit balance in microcents (1,000,000 microcents = $1.00) with formatted values. action=usage returns usage statistics. Read-only; call it before an expensive crawl or batch to confirm there are enough credits.

Manage change monitors. action=create watches a URL on a cron schedule and notifies by webhook when content changes; action=list returns your monitors; action=delete removes one by monitor_id (it stops running and cannot be restored). Each check spends credits like a scrape.

Manage recurring scrape schedules. action=create runs a scrape of one or more URLs on a cron expression; action=list returns your schedules; action=delete removes one by schedule_id (it stops triggering). Every run spends credits like a scrape; minimum intervals depend on your balance tier.

Start an execution of a workflow you saved in the AlterLab dashboard. Optional input_data is passed to the workflow's webhook trigger node. Returns run_id, workflow_id and the initial status. The run spends credits for the steps it executes.

Submit a plan of scrape and search steps (beta feature) with a required max_credits budget. Returns the run id, its state and one summed estimate; nothing executes until alterlab_run_approve (or auto_approve when the estimate fits the budget). Use dry_run to validate and estimate without storing a run. The same idempotency_key with the same plan returns the original run. Requires the agent-runs beta to be enabled for the account.

Approve a run that is awaiting approval (beta feature). The budget is reserved in one debit before any step starts; an insufficient balance returns 402 and no step runs. Optionally pass max_credits to lower the budget, or to raise it up to the run estimate. Approving an already approved run is a no-op that returns the current state. Spends credits up to the reserved budget; unused credits are refunded when the run ends.

Read a run's progress events in order (beta feature). Events such as step.started, step.completed, budget.warning and run.succeeded in seq order. The call returns once the run is finished and drained or the server closes the stream. Pass last_event_id from a previous call to receive only newer events. Returns events, last_event_id and truncated.

Get the current state of a run (beta feature): status, estimate, credits spent and a summary of each step. Poll until the state is terminal (succeeded, partial, failed, cancelled or budget_exhausted).

Stop the pending steps of a run (beta feature) and refund the unused part of the reserved budget. Steps already in flight settle first.