tavily

Tavily web search with optional LLM-generated answer

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).

get/tavily/search

Request

  • Base URL: https://www.socialcrawl.dev/v1
  • URL: https://www.socialcrawl.dev/v1/tavily/search
  • Auth: API key in header x-api-key

Query parameters

querystring required

The search query: natural-language free text.

search_depth'basic' | 'advanced' | 'fast' | 'ultra-fast'

Latency-vs-relevance tradeoff. basic is the default; advanced unlocks chunks_per_source and higher-relevance ranking.

topic'general' | 'news' | 'finance'

Search category. Defaults to general. Use news for time-sensitive queries and finance for market data.

time_range'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y'

Time window relative to now. Accepts day / week / month / year (or shorthand d / w / m / y).

max_resultsinteger

Number of results to return (1-20). Defaults to 5.

chunks_per_sourceinteger

Max relevant chunks returned per source (1-5). Only honoured when search_depth=advanced. Defaults to 3.

include_imagesboolean

Include images alongside the result content.

include_image_descriptionsboolean

Include AI-generated descriptions for the returned images.

include_answerboolean

Include an LLM-generated answer string synthesised from the top sources.

include_raw_contentboolean

Include the raw HTML/text alongside the cleaned content.

include_domainsstring

Comma-separated list of domains to restrict results to (e.g. nytimes.com,reuters.com).

exclude_domainsstring

Comma-separated list of domains to exclude from results.

countrystring

ISO 3166-1 alpha-2 country code to bias results toward.

start_datestring

Inclusive lower bound on result publish date (YYYY-MM-DD).

end_datestring

Inclusive upper bound on result publish date (YYYY-MM-DD).

Headers

Cache-Controlstring

Send no-cache to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the no-cache directive triggers this. See the Response Schema guide for details.

Idempotency-Keystring

Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives 409 IDEMPOTENCY_IN_PROGRESS with a Retry-After of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0, idempotent_replay becomes true, and credits_remaining is refreshed to the current balance. A known current balance appears in both the body and X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use Accept: application/json when sending this header. The unsupported key-plus-SSE combination is rejected before billing.

Response

Successful response

successboolean required

Whether the request succeeded

platformstring required

Platform name

endpointstring required

API endpoint path

credits_usedinteger required

Number of credits consumed

credits_remaininginteger nullable required

Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.

request_idstring required

Unique request identifier for support

cachedboolean required

Whether the response was served from cache

idempotent_replayboolean

True only when this response is an idempotency replay

Example response

{
  "success": true,
  "platform": "tavily",
  "endpoint": "/v1/tavily/search",
  "credits_used": 1,
  "credits_remaining": 4999,
  "request_id": "req-abc123",
  "idempotent_replay": true,
  "meta": {
    "hint": {
      "code": "search_multi",
      "message": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged.",
      "method": "GET",
      "path": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.