# Tavily Search

> Real-time web search built for LLMs and agents - returns ranked results with relevant content snippets, an optional LLM-generated answer, raw page content, images and domain/date filters. 19 credits per basic search, 38 per advanced search.

- **Provider**: tavily-search
- **Model ID**: tavily/search
- **Category**: web_search
- **Credits**: from 19 for the default configuration — varies by input, see Pricing
- **Pricing Type**: formula

## API Endpoint

Base URL: https://api.core.today/v1

### Create Prediction
POST /predictions

### Get Status
GET /predictions/{job_id}

### Cancel
DELETE /predictions/{job_id}

## Authentication

Header: `X-API-Key: YOUR_API_KEY`

## Input Parameters

- `query` (string, **required**): The search query. Write it in the language you want results in.
- `end_date` (string, optional): Only results published or updated before this date (YYYY-MM-DD).
- `country` (string, optional): Boost results from a country, as a lowercase English name (e.g. south korea, united states). topic=general only.
- `include_favicon` (boolean, optional): Add each result's favicon URL. (Default: `false`)
- `exact_match` (boolean, optional): Only results containing the quoted phrases in the query. (Default: `false`)
- `auto_parameters` (boolean, optional): Let Tavily pick parameters from the query intent (explicit values still win). May switch to advanced search - reserved at the advanced price and settled on the credits Tavily actually charged. (Default: `false`)
- `chunks_per_source` (integer, optional): Maximum relevant content chunks per source (1-3, default 3). Applies to basic, advanced and fast. (Range: min: 1, max: 3)
- `language` (string, optional): Boost results in a language - ISO 639-1 code or English name (e.g. ko, en).
- `include_domains` (array, optional): Only return results from these domains (e.g. ["core.today"]).
- `include_images` (boolean, optional): Add query-related images and per-result images. (Default: `false`)
- `safe_search` (boolean, optional): Filter adult or unsafe content. Not supported for fast or ultra-fast. (Default: `false`)
- `search_depth` (string, optional): basic is a balanced generic search; advanced returns the most relevant content chunks at higher latency (2x price); fast and ultra-fast trade relevance for latency. (Default: `basic`; Options: `basic`, `advanced`, `fast`, `ultra-fast`)
- `time_range` (string, optional): Only results published or updated within this window. (Options: `day`, `week`, `month`, `year`)
- `topic` (string, optional): Search category. news returns recent articles with published dates. (Default: `general`; Options: `general`, `news`, `finance`)
- `max_results` (integer, optional): Maximum number of results (0-20). Omit for Tavily's default. (Range: min: 0, max: 20)
- `include_answer` (string, optional): Add an LLM-generated answer to the query. advanced is more detailed. Omit for no answer. (Options: `basic`, `advanced`)
- `include_published_date` (boolean, optional): Add published_date to each result (always on for topic=news). (Default: `false`)
- `exclude_domains` (array, optional): Never return results from these domains.
- `include_image_descriptions` (boolean, optional): Add a text description to each image (needs include_images). (Default: `false`)
- `include_raw_content` (string, optional): Add the cleaned full page content of each result in this format. Omit for snippets only. (Options: `markdown`, `text`)
- `start_date` (string, optional): Only results published or updated after this date (YYYY-MM-DD).

## Example Request

```json
{
  "model": "tavily/search",
  "input": {
    "topic": "general",
    "max_results": 5,
    "search_depth": "basic",
    "include_answer": "basic",
    "query": "latest AI video generation models 2026"
  }
}
```

## Response Format

```json
{
  "job_id": "abc123",
  "status": "pending",
  "provider": "tavily-search",
  "model": "tavily/search",
  "created_at": "2026-01-01T00:00:00Z",
  "result": null,
  "error": null,
  "credits_used": null
}
```

Status values: `pending`, `processing`, `completed`, `failed`, `cancelled`

When the job is `completed`, `result` holds the output URL(s) or data and `credits_used` the net credits charged. When it is `failed`, `error` and `error_code` say why and the charge is refunded.

## Usage Flow

1. POST /predictions with model and input → receive job_id
2. Poll GET /predictions/{job_id} until status is `completed` or `failed`
3. Result contains output URL(s) or data

## Pricing

- Formula: `18.6 * max(1, min(max(depth, 2 * auto), billed))` credits
  - `auto`: the `auto_parameters` input (default 0)
  - `depth`: the `search_depth` input (default 1)
  - `billed`: 99

Default configuration: 19 credits.

These are list prices. The amount charged is rounded, and large charges are discounted progressively. `POST /predictions/estimate` with the same `model` and `input` returns the charge for that input without creating a job (an estimate when the price depends on the output).

## Output Type

json

## Tags

tavily, search, web-search, rag, agent

## Documentation

https://docs.tavily.com/documentation/api-reference/endpoint/search