openai-agents-scavio

Scavio real-time search tools for the OpenAI Agents SDK — 193 tools across 31 platforms, a URL reader and website map / crawl / batch, with one API key.

Google, YouTube, Amazon, Walmart, eBay, Target, Home Depot, Reddit, X, TikTok, TikTok Shop, Instagram, Threads, LinkedIn, Kuaishou, Zillow, Redfin, Booking.com, Airbnb, Tripadvisor, Yelp, Indeed, Glassdoor, the Apple App Store, Google Play, SEC EDGAR, Companies House, G2, Capterra, Google Ads Transparency and the Meta Ad Library — plus scavio_extract, which reads any URL as HTML, Markdown or plain text, and five opt-in website tools that map a site's URLs, crawl a whole site, or extract a list of pages in one job.

Nothing is held back for the MCP server any more: every live Scavio endpoint is a tool in this package.

Install

pip install openai-agents-scavio

Requires scavio>=0.23.0 — the version that made client.extract a callable namespace carrying map, crawl and batch. An older SDK cannot resolve the website tools.

Setup

Get a Scavio API key from the Scavio Dashboard (new accounts get 50 free credits, no credit card). Set SCAVIO_API_KEY or pass api_key= to the factory.

Usage

from agents import Agent, Runner
from openai_agents_scavio import get_scavio_tools

agent = Agent(
    name="Search Assistant",
    instructions="Search the web, shopping sites, and social platforms with Scavio.",
    tools=get_scavio_tools(),  # reads SCAVIO_API_KEY
)

result = Runner.run_sync(agent, "Find the top budget laptops on Amazon")
print(result.final_output)

Pick your platforms

193 tools is far more than any one agent should carry. Every platform is gated by an enable_* flag, all defaulting to True except enable_crawl (opt-in, because a crawl bills per page), so disable what you do not need:

tools = get_scavio_tools(
    enable_google=True,
    enable_reddit=True,
    enable_extract=True,
    enable_amazon=False,
    enable_walmart=False,
    enable_youtube=False,
    enable_tiktok=False,
    enable_instagram=False,
    # ... and so on for the rest
)

Pass all=True to register every tool regardless of the individual flags.

Tools

Each tool is named scavio_<platform>_<action> (scavio_google_search, scavio_ebay_search, scavio_sec_filings, scavio_meta_ads_search), takes flat scalar arguments, and returns the structured Scavio JSON response. Errors come back as {"error": "..."} rather than raising, so a failed call never crashes the run.

scavio_extract is the exception to the naming rule: it is a core endpoint rather than a platform, and it is the one to reach for when the agent has a URL and needs the page behind it.

tools = get_scavio_tools(enable_extract=True)  # scavio_extract(url, format=, mode=)

Map, crawl and batch

When one page is not enough, enable_crawl=True adds five website tools: scavio_map_website, scavio_crawl_website, scavio_crawl_status, scavio_batch_extract and scavio_batch_status. Map answers in one call. Crawl and batch start a background job, wait up to wait_seconds (default 45, max 300) for it to finish, and return the job's status with its first page of results (10 by default) either way. A job that is still queued or running when the wait ends keeps going: the agent reads the rest, free, with the matching status tool and data.id. That keeps an agent turn bounded while a large crawl (up to 6 hours) runs on.

agent = Agent(
    name="Docs Reader",
    instructions="Map the site first, then crawl only the section you need.",
    tools=get_scavio_tools(enable_crawl=True, enable_extract=True, enable_google=False),
)
result = Runner.run_sync(agent, "Crawl hono.dev/docs (max 25 pages) and summarise the routing guide")

Pricing. Map costs 1 credit in normal mode (advanced up to 2, ultra up to 10, priced by what the call needed). Crawl and batch bill per successful page at extract's price for the mode -- normal and advanced 1 credit, ultra 2 -- while failed and skipped pages are free; if your balance runs out the job stops cleanly with stopped_reason: "insufficient_credits". Reading a job is free. Crawl and map obey the site's robots.txt; results are kept for 3 days. Plan limits (pages per crawl / active jobs / URLs per batch): Free 10/1/10, PAYG 100/1/50, Project 500/2/100, Bootstrap 2,000/3/500, Startup 5,000/5/1,000, Growth 10,000/10/1,000. Webhooks, idempotency keys and cancellation are on the REST API and the scavio SDK (client.extract.cancel_crawl(...)), not exposed as agent tools.

Start with the resolver on lookup-first platforms

Five platforms are keyed by an id you have to look up first. Give the agent the resolver alongside the endpoint, or it will guess an id and get a 404:

Credits

Most tools cost 1 credit per call: every Google, Amazon, Reddit, X, TikTok, TikTok Shop, eBay, Target, Zillow, Redfin, Airbnb, Booking.com, App Store, Glassdoor, SEC EDGAR, Companies House, Google Ads Transparency and Meta Ad Library tool, plus most YouTube and LinkedIn ones. The exceptions:

These surfaces are body-priced — the cost depends on what you send, not on which tool you call:

Each tool's own description states its price. See scavio.dev/docs.

Notes on specific platforms

• Walmart — device, delivery_zip and store_id were retired. Sending them is not an error: the response carries a warnings[] array saying they were ignored. domain was not retired and is the price-bearing parameter. scavio_walmart_offers returns the buy-box seller only, not the full offer list, and scavio_walmart_seller_products returns roughly the first 40 server-rendered items with no pagination at all.
• Amazon — country (a two-letter marketplace code; the UK is gb, not uk) replaced domain in 2026-07, and sort_by, pages, category_id, merchant_id, language, currency, device, zip_code and autoselect_variant are gone. The marketplace ignored all of them, so they were removed rather than kept as silent no-ops. Rank and filter yourself.
• Google — v2 only. /api/v1/google was sunset on 2026-08-04 and returns 410, and the v1 vocabulary (country_code, language, page, search_type, light_request) went with it. start is a 0-based result offset, not a page.
• LinkedIn — five endpoints (person contact info, company people, company jobs, people search, post search) were withdrawn upstream and always return 410. They are deliberately not tools. Use scavio_linkedin_search_jobs with a company name instead of the retired per-company job listing.
• eBay — scavio_ebay_seller is a storefront profile, not a catalogue. To page a seller's inventory, call scavio_ebay_search with seller set and no query.

Also available via MCP

If you would rather not install anything, the same endpoints are served by the hosted MCP server:

from agents import Agent
from agents.mcp.server import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    name="scavio",
    params={"url": "https://mcp.scavio.dev/mcp", "headers": {"x-api-key": "sk_live_..."}},
)
agent = Agent(name="Search Assistant", mcp_servers=[server])

Links

• Scavio: https://scavio.dev
• Docs: https://scavio.dev/docs/openai-agents
• Dashboard: https://dashboard.scavio.dev