# 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?