metalift-sdk

Official Python SDK for Metalift — turn any URL into agent-ready markdown, HTML, or structured data.

Install

pip install metalift-sdk

Requires Python 3.10+.

Quick start

from metalift_sdk import Metalift

client = Metalift(api_key="YOUR_API_KEY")

result = client.scrape(
    "https://example.com",
    formats=["markdown"],
)
print(result["data"]["markdown"])

Get an API key from the Metalift dashboard. New accounts receive 1,000 free credits/month.

Web search (decoupled from scrape)

Search returns top 10 SERP snippets (2 credits). See Release notes for availability on Metalift Cloud.

serp = client.search("docker docs")
page = client.scrape(serp["results"][0]["url"], formats=["markdown"])

If search returns Not Found on api.metalift.ai, upgrade to metalift-sdk>=1.0.6 for a clearer error message.

Agents / MCP

REST batch / crawl below match MCP tools metalift_batch_scrape / metalift_crawl (API key). Keyless agents: Agentic Wallet or Charge-over-MCP https://mcp.metalift.ai/sse (@metalift/mcp ≥ 1.0.19 on the host). Do not mix wallet + Metalift MCP for the same job.

Configuration

from metalift_sdk import Metalift

client = Metalift(
    api_url="https://api.metalift.ai",  # default
    api_key="YOUR_API_KEY",
    timeout=60.0,
)

Environment variables are also supported:

Metalift Cloud requires X-B2B-Attestation: I-confirm-B2B-use on authenticated requests. metalift-sdk ≥ 1.0.11 sends this header automatically.

API

Scrape

client.scrape(
    "https://example.com",
    formats=["markdown"],
    render="auto",
    only_main_content=True,
    strategy="default",
)

Batch scrape

client.batch(
    ["https://example.com", "https://example.org"],
    async_=True,
    scrape_options={"formats": ["markdown"]},
)

Crawl and map

crawl_job = client.crawl("https://example.com", limit=50)
map_result = client.map("https://example.com", limit=100)

Async jobs

job = client.crawl("https://example.com", limit=20)
completed = client.wait_for_job(job["job_id"])
print(completed["status"], completed.get("data"))

Strategies and protected sites

strategies = client.list_strategies()
protection = client.list_protection_types()

client.scrape(
    "https://www.walmart.com/ip/EXAMPLE",
    strategy="retail",
    formats=["markdown"],
)

client.fetch_session(url="https://www.walmart.com/", domain="www.walmart.com")

Session cookies

client.seed_session(
    domain="example.com",
    cookies=[{"name": "session", "value": "...", "domain": "example.com", "path": "/"}],
)

Errors

API failures raise MetaliftError:

from metalift_sdk import Metalift, MetaliftError

try:
    client.scrape("https://example.com")
except MetaliftError as exc:
    print(exc.status_code, exc.detail)

Links

• Documentation
• API reference
• Support

License & distribution

metalift-sdk is proprietary software licensed under the terms in LICENSE. Use, copying, modification, and redistribution are not permitted except as expressly authorized by Metalift.

The package is published on the public Python Package Index (PyPI) so customers can install it with pip install metalift-sdk. Publishing on PyPI does not make the software open source: the wheel and source archive are publicly downloadable, but legal use remains governed by the proprietary license.

Do not commit API keys or other credentials into your application code. Pass them at runtime via the api_key argument or the METALIFT_API_KEY environment variable.