Tavily APIRun Tavily web search, extract, map, and crawl as structured JSON with one SocialCrawl API key. Same success envelope and credit model as every other platform. Reads are priced in credits.
4 active endpoints. Standard tier, 1 credit each.
Four live read endpoints for Tavily web grounding. Search with optional answer, multi-URL extract, site map, and multi-page crawl. Data API only. No second Tavily account required on your side.
/v1/tavily/searchRanked web results for a natural-language query. Optional include_answer for an LLM synthesis. Depth, topic, time_range, domain filters, and max_results control scope.
query, search_depth, topic, time_range, max_results, include_answer, include_domains, exclude_domains
/v1/tavily/extractClean text from one URL or a CSV of up to 20. Markdown or text format. Advanced extract depth for harder pages. Failed URLs are reported alongside successes.
urls (CSV, max 20), extract_depth, format
/v1/tavily/mapDiscover URLs from a root without full page bodies. Depth, breadth, limit, and path or domain filters. Faster than crawl when you only need coverage.
url, depth, breadth, limit
/v1/tavily/crawlMulti-page crawl with extracted content per page. Natural-language instructions guide path selection. Same filter family as map, plus extract depth and format.
url, limit, extract_depth, format
Returns ranked web search results for a query, and optionally a written answer put together from the top sources.
Use it when you want search results you can narrow by domain, date, or topic, with a short written answer alongside them if you ask for one.
query · The search query — natural-language free text.
$ curl https://www.socialcrawl.dev/v1/tavily/search?query=claude+opus+4.7+release+notes \
-H "x-api-key: sc_YOUR_API_KEY"// Running this live needs your own API key — hit "Try it" to see an example responseTavily is a normal SocialCrawl surface. You call GET /v1/tavily/… with an API key, spend credits on live misses, and get a single JSON envelope back. Web grounding without holding a second Tavily key in your app.
Send your key in the x-api-key header. The same key works for social platforms, Universal Search, Google Trends, and Tavily.
All four routes are GET. Pass query, urls, or url plus optional depth and filter params. We map query strings into Tavily's JSON body server-side before upstream.
Each live miss costs 1 credit (standard tier). Cache hits cost 0. Empty or hard failures refund. Bad params return 400 with no charge.
Every response is success, data, credits_used, credits_remaining, request_id, cached. Search may include results and answer. Extract, map, and crawl return their Analytics payloads under data.
Most products search first, extract the winners, map a docs root when coverage matters, then crawl only the paths they need.
GET /v1/tavily/search?query=…Ranked results[] and optional answer
Find candidate URLs and a short synthesis before deeper reads.
GET /v1/tavily/extract?urls=…Clean content rows per URL (up to 20)
Turn result links into AI-ready text without a second scraper.
GET /v1/tavily/map?url=…Discovered URL list from a root
Enumerate site structure before paying for full page bodies.
GET /v1/tavily/crawl?url=…Pages with extracted content under instructions
Pull multi-page docs or product trees in one guided run.
GET /v1/tavily/search
?query=best+web+scraping+apis
&include_answer=true
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/tavily/extract?urls=https://example.com{
"success": true,
"data": {
"results": [],
"answer": "…"
},
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}Tavily routes use the Analytics archetype so answer, results, and crawl rows are not stripped by list-only mappers.
results[] ranked hits; optional answer; query metadata (depth, time_taken, total_results)
per-URL content rows, format, failures listed alongside successes
map: URL list from sitegraph; crawl: pages with extracted content
Same request lifecycle as every other /v1 platform endpoint. Tavily is not a sidecar SDK in your process.
Next.js catch-all routes into the Hono social API. We mint a request_id, authenticate the key, then enforce rate limit (600/min) and concurrency (50 in flight per key).
Registry lookup finds tavily/search, extract, map, or crawl. Required params (query, urls, or url) are checked first. Invalid input returns 400 with no charge. Valid calls debit 1 credit atomically before upstream work.
A deterministic cache key is built from platform, resource, and params. Hit: return immediately, credits_used = 0. Miss: SocialCrawl's Tavily fetcher POSTs to api.tavily.com with house credentials. You do not attach a Tavily bearer token.
Upstream JSON is kept under the Analytics archetype (including answer on search), wrapped in the success envelope, and logged for billing audit.
Billing rules that matter in production
Tavily is web grounding for agents and research. We proxy the four public operations so your product stays on one SocialCrawl key.
Web search with optional answer, clean URL extract, sitegraph map, and multi-page crawl. Complements social reads when you need open-web context.
Dedicated Tavily fetcher translates GET query params into Tavily's JSON POST body. Upstream is api.tavily.com with SocialCrawl house auth. Your app only sends x-api-key.
A unified JSON envelope: success, data, credits_used, request_id, cached. Search preserves results and answer. Extract, map, and crawl return their native Analytics payloads.
No Tavily dashboard login. No write or index management. extract is capped at 20 URLs per call. map returns URLs without full bodies unless you crawl.
The jobs this API is most often used for.
Agent web grounding and docs ingestion
Callers use search with include_answer for grounding, extract for result URLs, and map then crawl for documentation trees. Same key as social endpoints reduces tool sprawl. Full Tavily surface on the SocialCrawl key at 1 credit per live call. No second vendor account in the customer app for these four routes.
Search and extract are typically a few seconds on live miss. Map and crawl scale with depth, breadth, and limit. Cache hits return immediately at 0 credits.
The jobs Tavily data is most often used for. Each one is a full recipe with the endpoint chain and pricing.
Common ways teams put this data to work, and the stack each one tends to run.
search with include_answer for grounding, then extract on cited URLs before embedding.
map a docs root, then crawl with instructions to pull only API or product pages.
Add open-web context next to social reads without provisioning a separate Tavily key in production.
Each live Tavily call is 1 credit. Cache hits are free. Search takes query. Extract takes urls. Map and crawl take a root url.
curl "https://www.socialcrawl.dev/v1/tavily/search?query=best+web+scraping+apis&include_answer=true" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/tavily/extract?urls=https://example.com" \
-H "x-api-key: sc_your_api_key_here"Same key as the rest of the catalog
Every endpoint returns structured JSON in a unified envelope. Computed fields such as engagement rate and content category are included only where the endpoint supports them and the required source inputs are present.
Same Tavily data, two very different paths. Auth, rate limits, schema, and cost — side by side.
| Feature | SocialCrawl | Tavily API (direct) |
|---|---|---|
| Authentication | One x-api-key shared with 47 other platforms | Separate Tavily account and API key |
| Setup | GET requests at /v1/tavily/{resource} in the same envelope as your other sources | Tavily SDK or REST with its own response format |
| Pricing | 1 credit per call from one shared balance | Separate plan with its own monthly credit allotment |
| Response schema | Unified SocialCrawl JSON envelope across search, extract, map, and crawl | Tavily-native response shapes |
| Data coverage | Search, extract, map, and crawl, plus Perplexity and social search on the same key | Full Tavily surface with every native parameter |
| Free tier | 100 free credits, no credit card | Free tier with monthly credits on Tavily's own plan |
Authentication
Setup
Pricing
Response schema
Data coverage
Free tier
Find answers to frequently asked questions about SocialCrawl's API, pricing, and capabilities.
Contact usAsk AI about SocialCrawl