# Tavily Search - Core.Today AI API

> 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
- **Model ID**: tavily/search
- **Category**: Web Search
- **Credits**: 19 per search (basic/fast/ultra-fast; 38 for advanced)
- **Speed**: Fast
- **Quality**: High

## Features
- Results ranked for LLM grounding, with relevant content chunks per source
- Optional LLM-generated answer (basic or advanced)
- Full page content as markdown or text with include_raw_content
- general / news / finance topics, time range and date filters
- Include or exclude domains, country and language boosting

## Use Cases
- Grounding chatbot and agent answers in current web information (RAG)
- News monitoring and recent-event lookups
- Research assistants that cite their sources

## API Endpoint

Base URL: https://api.core.today/v1
Create Prediction: POST /predictions
Get Status: GET /predictions/{job_id}

## Authentication
Header: X-API-Key: YOUR_API_KEY

## Input Parameters

### Required
- **query**: string - The search query. Write it in the language you want results in.

### Optional
- **search_depth**: string (default: basic) - 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.
  Options: basic, advanced, fast, ultra-fast
- **topic**: string (default: general) - Search category. news returns recent articles with published dates.
  Options: general, news, finance
- **max_results**: integer - Maximum number of results (0-20). Omit for Tavily's default.
- **chunks_per_source**: integer - Maximum relevant content chunks per source (1-3, default 3). Applies to basic, advanced and fast.
- **time_range**: string - Only results published or updated within this window.
  Options: day, week, month, year
- **start_date**: string - Only results published or updated after this date (YYYY-MM-DD).
- **end_date**: string - Only results published or updated before this date (YYYY-MM-DD).
- **include_answer**: string - Add an LLM-generated answer to the query. advanced is more detailed. Omit for no answer.
  Options: basic, advanced
- **include_raw_content**: string - Add the cleaned full page content of each result in this format. Omit for snippets only.
  Options: markdown, text
- **include_images**: boolean (default: false) - Add query-related images and per-result images.
- **include_image_descriptions**: boolean (default: false) - Add a text description to each image (needs include_images).
- **include_favicon**: boolean (default: false) - Add each result's favicon URL.
- **include_published_date**: boolean (default: false) - Add published_date to each result (always on for topic=news).
- **include_domains**: array - Only return results from these domains (e.g. ["core.today"]). Up to 300.
- **exclude_domains**: array - Never return results from these domains. Up to 150.
- **country**: string - Boost results from a country, as a lowercase English name (e.g. south korea, united states). topic=general only.
- **language**: string - Boost results in a language - ISO 639-1 code or English name (e.g. ko, en).
- **auto_parameters**: boolean (default: false) - 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.
- **exact_match**: boolean (default: false) - Only results containing the quoted phrases in the query.
- **safe_search**: boolean (default: false) - Filter adult or unsafe content. Not supported for fast or ultra-fast.

## Examples

### Search with an answer
Five results plus a short LLM-generated answer.
```json
{
  "model": "tavily/search",
  "input": {
    "query": "latest AI video generation models 2026",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": "basic"
  }
}
```

### Recent news from Korean sources
News from the past week, boosted toward Korea and Korean.
```json
{
  "model": "tavily/search",
  "input": {
    "query": "생성형 AI 규제",
    "topic": "news",
    "time_range": "week",
    "language": "ko",
    "max_results": 10
  }
}
```

### Deep search on chosen domains
advanced search limited to two domains, with full page content as markdown.
```json
{
  "model": "tavily/search",
  "input": {
    "query": "Seedance 2.5 reference to video pricing",
    "search_depth": "advanced",
    "include_domains": [
      "core.today",
      "byteplus.com"
    ],
    "include_raw_content": "markdown"
  }
}
```

## Response Format
```json
{
  "job_id": "abc123",
  "status": "pending | processing | completed | failed",
  "result": "URL or data (when completed)"
}
```

## Usage Flow
1. POST /predictions with model and input -> receive job_id
2. GET /predictions/{job_id} -> poll until status is completed or failed
3. Result contains output URL(s)

## Tips
- The result is Tavily's JSON as-is: results[] (title, url, content, score), answer, images and usage.credits (the billed unit)
- Links in results are the original pages - they are not copied to your storage
- For full text of specific pages you already have, use tavily/extract instead of include_raw_content
- Write the query in the language you want results in; language and country only boost, they do not filter

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