crewai-scavio

CrewAI integration for the Scavio Search API, a search API for AI agents. Provides 201 search tools -- one per Scavio endpoint, plus free status reads for crawl and batch jobs -- for use with CrewAI agents:

• Search and web -- Google (web, AI Mode, news, maps, shopping, flights, hotels, trends) and ScavioExtractTool, which reads any URL as HTML, Markdown or plain text, plus ScavioExtractMapTool, ScavioExtractCrawlTool and ScavioExtractBatchTool to map a site's URLs, crawl a whole site, or extract a list of pages in one job
• Retail -- Amazon, Walmart, eBay, Target, Home Depot, TikTok Shop
• Social and video -- YouTube, TikTok, Instagram, Reddit, X (Twitter), Threads, Kuaishou
• Real estate -- Zillow, Redfin
• Travel and local -- Booking.com, Airbnb, Tripadvisor, Yelp
• Jobs and employers -- LinkedIn, Indeed, Glassdoor
• Apps -- Apple App Store, Google Play
• Company and filings -- SEC EDGAR, Companies House (UK)
• Software reviews -- G2, Capterra
• Ad transparency -- Google Ads Transparency, Meta Ad Library

Installation

pip install crewai-scavio

Setup

Get a free API key at dashboard.scavio.dev and set it as an environment variable:

export SCAVIO_API_KEY="sk_live_..."

Quick Start

from crewai import Agent, Crew, Task
from crewai_scavio import ScavioSearchTool

search_tool = ScavioSearchTool()

researcher = Agent(
    role="Research Analyst",
    goal="Find the latest information on any topic",
    backstory="An expert researcher who finds accurate, up-to-date information.",
    tools=[search_tool],
    verbose=True,
)

research_task = Task(
    description="Research the top 3 trends in AI agents for 2026.",
    expected_output="A summary of the top 3 AI agent trends with sources.",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True,
)

result = crew.kickoff()
print(result)

Available Tools

Usage Examples

Amazon Product Search

from crewai_scavio import ScavioAmazonSearchTool, ScavioAmazonOffersTool

amazon_tool = ScavioAmazonSearchTool(country="us", max_results=5)
result = amazon_tool.run("wireless noise cancelling headphones")

offers_tool = ScavioAmazonOffersTool()
offers = offers_tool.run(asin="B08N5WRWNW")

Amazon changed in 0.4.0 (breaking). The Amazon endpoint changed. domain is replaced by country, a two-letter marketplace code (us, gb -- the UK is gb, not uk -- de, jp, ...). sort_by, pages, category_id, merchant_id, language, currency, device, zip_code and autoselect_variant are gone: the marketplace ignores all of them, and sort_by was verified to return the identical unordered set for every value, so they are removed rather than kept as silent no-ops. Product responses are normalized now -- price is a number with a sibling currency, not an object, and buybox is gone (use ScavioAmazonOffersTool).

Google Web Search

Every native v2 param -- gl, hl, start, google_domain, device, location, uule, lr, cr, safe, filter, time_period, nfpr, include_html, resolve_ai_overview -- is an argument the agent can set per call. start is a result OFFSET, not a page number: 0 is page 1, 10 is page 2.

from crewai_scavio import ScavioSearchTool

search_tool = ScavioSearchTool(max_results=10)
page_two = search_tool.run(
    query="best running shoes",
    gl="de",
    hl="de",
    start=10,
    time_period="last_week",
)

Constructor values are defaults for when the agent omits an argument. The v1 spellings country_code, language and page still work there and seed gl, hl and start; anything the agent passes wins.

YouTube Video Search

sort_by, type, duration and upload_date moved into the tool's argument schema in 0.7.0, alongside cursor and the feature flags (hd, four_k, subtitles, creative_commons, live, hdr, vr180, video_360, video_3d, and the features list). Setting them on the constructor still works as a default.

from crewai_scavio import ScavioYouTubeSearchTool

youtube_tool = ScavioYouTubeSearchTool(max_results=5, sort_by="relevance")

result = youtube_tool.run(
    query="CrewAI tutorial",
    sort_by="view_count",
    duration="long",
    upload_date="this_month",
)

# Page 2: pass back data.next_cursor from the previous response.
more = youtube_tool.run(query="CrewAI tutorial", cursor="<next_cursor>")

TikTok Pagination

TikTok's cursor is a STRING -- "0" for the first page, then the cursor value the previous response returned. A numeric cursor is a 400. count is a number, capped per endpoint (30 on the video lists, 50 on comments, 20 on the follow lists).

from crewai_scavio import ScavioTikTokSearchVideosTool, ScavioTikTokUserFollowersTool

videos_tool = ScavioTikTokSearchVideosTool(max_results=20)
page_two = videos_tool.run(
    keyword="cooking recipe", cursor="20", count=30, publish_time="7"
)

# Followers/followings break the pattern: no cursor, page with
# page_token plus min_time instead.
followers_tool = ScavioTikTokUserFollowersTool(max_results=20)
followers = followers_tool.run(
    sec_user_id="<sec_user_id>", page_token="<next_page_token>", min_time=1720000000
)

Walmart Product Search

Walmart changed in 0.8.0 (breaking). Walmart moved to a new upstream and gained five endpoints. device, delivery_zip and store_id are retired: sending them now returns a 200 with a warnings[] array explaining why, so they are removed here rather than kept as silent no-ops. start_page still works as a deprecated alias, but page is the field to use. ScavioWalmartProductTool takes no domain -- walmart.ca product pages cannot be fetched at all.

domain is the price-bearing parameter: com and ca cost 1 credit, com.mx costs 2. Search and category accept it; the other five do not.

from crewai_scavio import ScavioWalmartSearchTool, ScavioWalmartOffersTool

walmart_tool = ScavioWalmartSearchTool(max_results=10)
result = walmart_tool.run(
    query="air fryer",
    page=2,
    sort_by="price_low",
    min_price=50,
    max_price=200,
    fulfillment_speed="tomorrow",
)

# Offers returns the BUY-BOX seller only -- there is no way to page
# through the other sellers.
offers = ScavioWalmartOffersTool().run(product_id="13544111159")

ScavioWalmartSellerProductsTool wants the NUMERIC catalog seller id, the seller_catalog_id field on a product, search or offers row. The GUID seller_id 404s.

Reddit Search

Results come back in relevance order under data.results. The endpoint takes only query and cursor -- there is no sort or result-type filter. Paginate by passing back the previous response's data.next_cursor.

from crewai_scavio import ScavioRedditSearchTool

reddit_tool = ScavioRedditSearchTool(max_results=10)
result = reddit_tool.run("AI agents")

/reddit/post returns a flat post object with no comments. Fetch the thread in a second call, then drill into a comment with its reply_cursor:

from crewai_scavio import (
    ScavioRedditCommentRepliesTool,
    ScavioRedditPostCommentsTool,
)

comments_tool = ScavioRedditPostCommentsTool(max_results=20)
comments = comments_tool.run(post_id="t3_1v6ngaf", sort="TOP")

# cursor is REQUIRED here and must be a comment's reply_cursor,
# not the feed's next_cursor.
replies_tool = ScavioRedditCommentRepliesTool()
replies = replies_tool.run(post_id="t3_1v6ngaf", cursor="<reply_cursor>")

The subreddit and user feeds return data.posts, not data.results. Sort values are uppercase, and RISING exists on the subreddit feed only.

Google Maps

Maps is a two-step lookup: search for the business, then use the place_id or data_id it returns. Google responses are flat -- there is no data wrapper.

from crewai_scavio import ScavioGoogleMapsReviewsTool, ScavioGoogleMapsSearchTool

maps_tool = ScavioGoogleMapsSearchTool(max_results=5)
places = maps_tool.run(query="coffee in brooklyn", gl="us")

reviews_tool = ScavioGoogleMapsReviewsTool(max_results=20)
reviews = reviews_tool.run(place_id="<place_id>", sort_by="newest")

TikTok Shop

Two things to know before wiring these together:

1. ScavioTikTokShopProductTool resolves only about 44% of the product ids that ScavioTikTokShopSearchTool returns. Upstream has no detail data for the rest, so a not-found result is a normal outcome rather than an error -- skip the product instead of retrying. Search is a listing source, not the first leg of a reliable search-then-detail pipeline.
2. ScavioTikTokShopProductTool does not return a price. Upstream masks the digits on the product page, so price.current and price.original come back null. Exact prices are on ScavioTikTokShopSearchTool, ScavioTikTokShopShopProductsTool and ScavioTikTokShopCategoryProductsTool.

import json

from crewai_scavio import (
    ScavioTikTokShopSearchTool,
    ScavioTikTokShopProductTool,
    ScavioTikTokShopProductReviewsTool,
)

# Listing data, including the exact price
search_tool = ScavioTikTokShopSearchTool(max_results=10)
page = json.loads(search_tool.run(search="phone case"))
for product in page["data"]["products"]:
    print(product["title"], product["price"]["current"])

# Detail: rich, but priceless and only ~44% resolvable
detail_tool = ScavioTikTokShopProductTool()
detail = json.loads(detail_tool.run(product_id="1732293553906094315"))
if detail.get("not_found"):
    pass                                  # normal outcome: skip, do not retry

# Reviews: page with has_more, never with total_reviews (it drifts)
reviews_tool = ScavioTikTokShopProductReviewsTool(max_results=20)
reviews = json.loads(
    reviews_tool.run(product_id="1732293553906094315", page_size=100)
)

Reading Any URL

ScavioExtractTool is not tied to a platform: give it a URL and it returns the page as raw HTML, readability Markdown, or that Markdown flattened to plain text. mode is the price-bearing argument -- normal (the standard fetch) and advanced (renders JavaScript-built pages) cost 1 credit, ultra (the hardest pages) costs 2 -- and only a successful extraction is billed, so a dead link, bot wall or timeout costs nothing.

from crewai_scavio import ScavioExtractTool

extract_tool = ScavioExtractTool()
page = extract_tool.run(url="https://example.com/pricing", format="markdown")

# Hardest targets only: 2 credits, so do not reach for it first.
stubborn = extract_tool.run(url="https://example.com/gated", mode="ultra")

Map, Crawl and Batch

When one page is not enough. ScavioExtractMapTool answers in one call with a site's page URLs. ScavioExtractCrawlTool and ScavioExtractBatchTool start a background job, wait up to wait_seconds (default 45, max 300) for it to finish, and return the job's id, status, pages, credits_used, up to limit page results (default 10) and next_cursor. A job still queued or running when the wait ends keeps going: read it, and any further pages, with ScavioExtractCrawlStatusTool / ScavioExtractBatchStatusTool and the id. That keeps a task step bounded while a large crawl (up to 6 hours) runs on.

import json

from crewai_scavio import (
    ScavioExtractBatchTool,
    ScavioExtractCrawlStatusTool,
    ScavioExtractCrawlTool,
    ScavioExtractMapTool,
)

links = ScavioExtractMapTool().run(url="https://hono.dev/docs", limit=50)

job = json.loads(
    ScavioExtractCrawlTool().run(
        url="https://hono.dev/docs", max_pages=25, include_paths=["/docs/**"]
    )
)
if job["data"]["next_cursor"]:
    more = ScavioExtractCrawlStatusTool().run(
        id=job["data"]["id"], cursor=job["data"]["next_cursor"]
    )

batch = ScavioExtractBatchTool().run(
    urls=["https://example.com/", "https://hono.dev/docs/getting-started/basic"]
)

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; a job stops cleanly with stopped_reason: "insufficient_credits" if the balance runs out. 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. Cancellation, webhooks and idempotency keys exist on the REST API and in the scavio SDK, but are not tools here.

eBay Sold-Listing Price Research

sold=True searches completed listings that actually sold, which is what makes eBay a price-history source rather than another catalog. eBay publishes no headline count on that view, so total_results comes back null -- page until a page comes back short instead of trusting a total.

ScavioEbaySellerTool is a profile card and cannot enumerate a catalog. To page a seller's inventory, use search with seller set and no keyword.

from crewai_scavio import ScavioEbaySearchTool

ebay_tool = ScavioEbaySearchTool(max_results=20)
sold = ebay_tool.run(query="ps5 slim", sold=True, condition="used", per_page=120)

catalogue = ebay_tool.run(seller="musicmagpie", sort_by="newly_listed")

per_page accepts only 60, 120 or 240; eBay silently falls back to 60 for anything else.

Lookup-First Platforms

Five surfaces are keyed by an id you have to resolve first. Spend the lookup call rather than guessing the id:

import json

from crewai_scavio import ScavioSECFilingsTool, ScavioSECLookupTool

cik = json.loads(ScavioSECLookupTool().run(query="Apple"))["data"]["results"][0]
filings = ScavioSECFilingsTool(max_results=10).run(cik=cik["cik"], form="10-K")

Body-Priced Endpoints

Four surfaces cost a number that depends on the request body, not on the route. Budget for the expensive branch:

Configuration

All tools accept api_key as a parameter, or read from the SCAVIO_API_KEY environment variable:

tool = ScavioSearchTool(api_key="sk_live_...", max_results=10)

About Scavio

Scavio is a unified search API built for AI agents — one API key, structured JSON, no scraping or proxies. A real-time Tavily alternative and SerpAPI alternative with data from:

• Google Search API — SERP results, AI Mode, news, maps, shopping, flights, hotels, and trends
• Amazon Product API and Walmart Product API — product search and details
• YouTube API, TikTok API, and Instagram API — video and social media data
• Reddit API — posts, threaded comments, subreddit and user feeds
• X (Twitter), LinkedIn, Threads, and Kuaishou — tweets, profiles, timelines, company pages, and jobs
• eBay, Target, and Home Depot — retail search, product detail, and reviews
• Zillow and Redfin — listings, property detail, and market stats
• Booking.com, Airbnb, Tripadvisor, and Yelp — travel and local business data
• Indeed and Glassdoor — job postings, employer profiles, reviews, and salaries
• Apple App Store and Google Play — app listings and reviews
• SEC EDGAR and Companies House — filings, XBRL facts, officers, and UK register entries
• G2 and Capterra — B2B software ratings and review bodies
• Google Ads Transparency and the Meta Ad Library — competitor ad creatives

Get a free API key and explore the documentation. You can also compare Scavio vs alternatives on coverage and pricing.