Get one web page as clean, LLM-ready markdown (or text, HTML, JSON) in a single call; rendering and tier escalation are handled for you. Use when you have one URL and want its content; for an image use alterlab_screenshot, for 2-20 URLs alterlab_batch_scrape, for a whole site alterlab_crawl. Cost: from $0.0002 per page, up to $0.02 on the hardest pages; it starts at the cheapest tier that works and cache hits cost half. A 403/429, challenge page or empty JavaScript shell is retried on higher tiers automatically. Supports GET and POST via method, extraction via extraction_schema or extraction_prompt, cost caps via cost_controls, and browser actions via actions plus screenshot and generate_pdf; action_results has 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. A failure may carry next_action install_hands: reason, what Hands unlocks, install link, resume ref.

Turn content you already hold (HTML, text or markdown) into structured JSON fields such as prices, product info, contact details or custom fields, without fetching anything. 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.

Get a full-page PNG image of one URL, rendered in a real headless browser, when you need to see the page rather than read its text. Use when layout, charts or visual proof matter; for text content use alterlab_scrape. Cost: $0.004 per screenshot (browser tier). 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.

Fetch the status and result of an asynchronous scrape job by job_id. Use this when alterlab_scrape or alterlab_screenshot returns a job_id instead of content (a long-running scrape that outlived the synchronous wait window). Status values: queued, processing, succeeded, failed, rejected (rejected = not processed due to insufficient balance; stop polling and check the balance). Polling is free; do not re-run the scrape, which would be billed again.

Predict the credit cost of scraping a URL before you run it, for free. Use when cost matters or before a large job. Cost: free, 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.

Check your AlterLab account balance, status, and credit usage. Call this before expensive operations (batch scrapes, large crawls) to verify sufficient funds. Returns current balance in dollars, balance status (healthy/low/critical/exhausted), total deposited, and total spent. For a full spending breakdown by time window and top domains, use alterlab_get_usage instead. No parameters required — uses your API key for identification.

Get account usage for the current billing period — balance, credits consumed this period, account tier and entitlement source. Use this to track spend against your plan; use alterlab_check_balance for deposit and spend totals. No parameters required — uses your API key for identification.

Get the content of every page on a site in one job, 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. Cost: the alterlab_scrape rate per page crawled, from $0.0002 up to $0.02. Works on JavaScript-heavy and protected sites. 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.

Poll the status and results of an ongoing or completed crawl. Call this after alterlab_crawl to check progress and retrieve scraped pages. Status values: queued, running, completed, failed, cancelled. When completed, results contains the scraped page content.

Cancel an ongoing crawl and refund unused pre-debited credits. Already-scraped pages are kept and available via alterlab_crawl_status. Cancelled crawls cannot be resumed.

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

List every URL on a site via sitemap parsing and link extraction, without fetching page content, so you can scope work before reading anything. 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, with no polling. Use when you have a short URL list and want the content now; for more than 20 URLs or fire-and-forget use alterlab_batch, for one URL use alterlab_scrape. Cost: the alterlab_scrape rate per URL, from $0.0002 up to $0.02. Failed URLs report their error; successful ones return content. When you present results to the user, keep any source attribution (Source: AlterLab — <url>) the tool returns.

Queue up to 100 URLs as one asynchronous job and collect the results later by batch_id, so a large list never blocks your run. Use when you have more than 20 URLs or do not need results immediately; for 2-20 URLs with results now use alterlab_batch_scrape. Cost: the alterlab_scrape rate per URL, from $0.0002 up to $0.02. 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.

Poll the status and results of a submitted batch. Call this after alterlab_batch to check progress and retrieve scraped content. Status values: processing, completed, failed, partially_failed. When completed, results contains the content for each URL.

List all stored sessions for authenticated scraping. Sessions contain cookies for specific domains, allowing you to scrape content that requires login (e.g., Amazon order history, LinkedIn profiles). Use the returned session_id with alterlab_scrape to scrape authenticated pages.

Create a new stored session for authenticated scraping. Provide cookies from a logged-in browser session to enable scraping behind login walls. The session is stored securely and can be reused across multiple scrape requests via session_id. Requires consent=true (explicit GDPR consent to store the cookies); optional headers, expires_at, notes, auto_refresh/notification flags and organization sharing are supported.

Get detailed information about a specific stored session. Returns session status, cookie names, usage statistics (total requests, success rate), expiry info, and notes. Use this to inspect a session before deciding to validate, refresh, or delete it.

Update a stored session's properties. You can change the name, rotate cookies, update custom headers, set a new expiration, or add notes. When cookies are provided, they replace ALL existing cookies (not merged). Use this instead of delete+recreate when you need to rotate credentials.

Refresh a session by rotating its cookies and resetting failure counters. This is the preferred way to update cookies after re-authenticating in your browser. The session status is reset to active. If cookies are omitted, only the failure counters are reset.

Validate whether a stored session is still active and its cookies are valid. Run this before scraping if you suspect a session may have expired. Returns the session status and a reason if invalid.

Delete a stored session. This permanently removes the session and its cookies. Use this when a session is no longer needed or has been compromised.

List all public beta and GA features available on AlterLab, with your current opt-in state for each. Beta features require opting in; GA features are available to all users. Use alterlab_enable_beta_feature to opt in to any beta feature that interests you.

List all beta and GA features currently active on your account — a compact slug list for quick checks. Includes all GA features plus any beta features you have opted in to. Use this to verify which features are available before making API calls that require them.

Opt in to a beta feature on your AlterLab account. Beta features are experimental capabilities available before general release. This operation is idempotent — calling it when already opted in returns success. Use alterlab_list_beta_features to discover available feature slugs.

Opt out of a beta feature on your AlterLab account. This operation is idempotent — calling it when not opted in returns success. GA (generally available) features cannot be disabled.