# Tavily Search API (https://www.socialcrawl.dev/platforms/tavily/search)

> Runs a web search via Tavily and returns ranked results plus an optional LLM-generated `answer` synthesised from the top sources. Set `include_answer=true` to enable answer synthesis. Use `search_depth=advanced` for higher-relevance results (also unlocks `chunks_per_source`). Filter results to specific domains via `include_domains` (comma-separated), or exclude via `exclude_domains`. Time-bounded queries via `time_range` (`d` / `w` / `m` / `y`) or explicit `start_date` / `end_date` (YYYY-MM-DD).

TL;DR: `GET /v1/tavily/search` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | The search query — natural-language free text. |
| `search_depth` | no | Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking. (basic \| advanced \| fast \| ultra-fast) |
| `topic` | no | Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data. (general \| news \| finance) |
| `time_range` | no | Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`). (day \| week \| month \| year \| d \| w \| m \| y) |
| `max_results` | no | Number of results to return (1–20). Defaults to 5. |
| `chunks_per_source` | no | Max relevant chunks returned per source (1–5). Only honoured when `search_depth=advanced`. Defaults to 3. |
| `include_images` | no | Include images alongside the result content. |
| `include_image_descriptions` | no | Include AI-generated descriptions for the returned images. |
| `include_answer` | no | Include an LLM-generated answer string synthesised from the top sources. |
| `include_raw_content` | no | Include the raw HTML/text alongside the cleaned content. |
| `include_domains` | no | Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`). |
| `exclude_domains` | no | Comma-separated list of domains to exclude from results. |
| `country` | no | ISO 3166-1 alpha-2 country code to bias results toward. |
| `start_date` | no | Inclusive lower bound on result publish date (YYYY-MM-DD). |
| `end_date` | no | Inclusive upper bound on result publish date (YYYY-MM-DD). |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/tavily/search?query=claude%20opus%204.7%20release%20notes" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I run a Tavily web search with an API?

Send a GET request to /v1/tavily/search with your text in the query parameter and your SocialCrawl x-api-key. You get back ranked web results with title, URL, content snippet, and score — no separate Tavily key needed.

### Can Tavily search return an LLM-generated answer?

Yes. Set include_answer to get a short LLM-written answer summarising the top results alongside the raw result list. This is the pattern most teams use for RAG and agent grounding — one call gives you both the sources and a draft answer.

### What filters does the Tavily search endpoint support?

search_depth (basic or advanced), topic (general or news), time_range to bound recency, include_domains and exclude_domains to scope sources, max_results to cap the list, and include_images to return image URLs with the results.

### Is this a Tavily alternative or the real Tavily?

It is the real Tavily. SocialCrawl proxies api.tavily.com so you call genuine Tavily search through your one SocialCrawl key. If you want a different backend, the same key also reaches Perplexity Sonar and SocialCrawl's AI social search.

### How much does the Tavily Search API cost?

Each search costs 1 credit on the standard tier, regardless of how many results return. New accounts get 100 free credits with no credit card required — enough to test depth, topic, and domain filters many times before you pay.

See the full Tavily API: https://www.socialcrawl.dev/platforms/tavily

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to call Tavily web search through the SocialCrawl API
- Does the SocialCrawl Tavily search return an LLM answer?