# Tavily Search

**API:** Data API

**Endpoint:** `POST /v1/beta/tavily/search`

**Tags:** Web Search

웹을 검색하고 제목, URL, 콘텐츠 스니펫이 포함된 순위 결과를 반환합니다. query는 필수입니다. max_results로 결과 수를 제어하고 search_depth로 검색 모드를 선택합니다. answer, images, 원시 콘텐츠는 요청할 때만 반환됩니다. 리소스 사용 정보를 받으려면 include_usage를 설정하세요. usage.credits는 Felo 청구가 아닙니다.

### 가격 참고

- 과금 기준: 측정된 응답 단위.
- 참고 요청 추정치: USD 0.016.
- 단위 원가 기준: USD 0.008.
- 리소스 단위: `tavily_credit`.
- 참고 고객 배수: 1.0. 정산된 고객 금액에 다시 적용하지 마세요.
- 원가 기준은 0인 경우를 포함해 최종 고객 가격을 확정하지 않습니다.

참고용 메타데이터일 뿐이며, 계정 견적이나 보장된 가격 또는 지출 한도가 아닙니다. 리소스 크레딧은 Felo 크레딧이 아닙니다. 최종 청구는 Felo 청구 기록을 따릅니다.

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Request body

Required: **yes**

### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Tavily로 실행할 검색 쿼리입니다.",
      "example": "Who is Leo Messi?"
    },
    "search_depth": {
      "type": "string",
      "enum": [
        "advanced",
        "basic",
        "fast",
        "ultra-fast"
      ],
      "default": "basic",
      "description": "지연 시간과 관련성 간의 균형을 제어합니다. advanced는 지연 시간과 비용이 높은 대신 관련성이 가장 높고, basic은 균형 잡힌 옵션이며, fast와 ultra-fast는 지연 시간을 낮추는 데 최적화되어 있습니다."
    },
    "chunks_per_source": {
      "type": "integer",
      "default": 3,
      "description": "소스당 반환되는 관련 청크의 최대 수입니다.",
      "minimum": 1,
      "maximum": 3
    },
    "max_results": {
      "type": "integer",
      "default": 5,
      "description": "반환할 최대 검색 결과 수입니다.",
      "minimum": 0,
      "maximum": 20
    },
    "topic": {
      "type": "string",
      "enum": [
        "general",
        "news",
        "finance"
      ],
      "default": "general",
      "description": "검색 카테고리입니다."
    },
    "time_range": {
      "type": "string",
      "enum": [
        "day",
        "week",
        "month",
        "year",
        "d",
        "w",
        "m",
        "y"
      ],
      "description": "게시 날짜를 기준으로 결과를 필터링할 시간 범위입니다."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "지정한 시작 날짜 이후의 결과를 반환합니다.",
      "example": "2025-02-09"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "지정한 종료 날짜 이전의 결과를 반환합니다.",
      "example": "2025-12-29"
    },
    "include_answer": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "basic",
            "advanced"
          ]
        }
      ],
      "default": false,
      "description": "LLM 생성 답변을 포함합니다. true는 기본 답변 모드를 사용하고, basic 또는 advanced는 답변 생성 모드를 선택합니다."
    },
    "include_raw_content": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "markdown",
            "text"
          ]
        }
      ],
      "default": false,
      "description": "각 검색 결과에 정제 및 파싱된 콘텐츠를 포함합니다. true 또는 markdown은 markdown을 반환하고, text는 일반 텍스트를 반환하며 지연 시간이 늘어날 수 있습니다."
    },
    "include_images": {
      "type": "boolean",
      "default": false,
      "description": "이미지 검색을 수행하고 결과를 포함합니다."
    },
    "include_image_descriptions": {
      "type": "boolean",
      "default": false,
      "description": "include_images가 true일 때 각 이미지에 설명 텍스트를 추가합니다."
    },
    "safe_search": {
      "type": "boolean",
      "default": false,
      "description": "검색 결과에서 성인 또는 안전하지 않은 콘텐츠를 필터링합니다. 엔터프라이즈 전용이며, search_depth가 fast 또는 ultra-fast일 때는 지원되지 않습니다."
    },
    "include_favicon": {
      "type": "boolean",
      "default": false,
      "description": "각 결과의 파비콘 URL을 포함합니다."
    },
    "include_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "검색 결과에 특별히 포함할 도메인 목록입니다.",
      "maxItems": 300
    },
    "exclude_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "검색 결과에서 특별히 제외할 도메인 목록입니다.",
      "maxItems": 150
    },
    "country": {
      "type": "string",
      "description": "특정 국가의 검색 결과를 우선시합니다. topic이 general일 때만 사용할 수 있습니다.",
      "enum": [
        "afghanistan",
        "albania",
        "algeria",
        "andorra",
        "angola",
        "argentina",
        "armenia",
        "australia",
        "austria",
        "azerbaijan",
        "bahamas",
        "bahrain",
        "bangladesh",
        "barbados",
        "belarus",
        "belgium",
        "belize",
        "benin",
        "bhutan",
        "bolivia",
        "bosnia and herzegovina",
        "botswana",
        "brazil",
        "brunei",
        "bulgaria",
        "burkina faso",
        "burundi",
        "cambodia",
        "cameroon",
        "canada",
        "cape verde",
        "central african republic",
        "chad",
        "chile",
        "china",
        "colombia",
        "comoros",
        "congo",
        "costa rica",
        "croatia",
        "cuba",
        "cyprus",
        "czech republic",
        "denmark",
        "djibouti",
        "dominican republic",
        "ecuador",
        "egypt",
        "el salvador",
        "equatorial guinea",
        "eritrea",
        "estonia",
        "ethiopia",
        "fiji",
        "finland",
        "france",
        "gabon",
        "gambia",
        "georgia",
        "germany",
        "ghana",
        "greece",
        "guatemala",
        "guinea",
        "haiti",
        "honduras",
        "hungary",
        "iceland",
        "india",
        "indonesia",
        "iran",
        "iraq",
        "ireland",
        "israel",
        "italy",
        "jamaica",
        "japan",
        "jordan",
        "kazakhstan",
        "kenya",
        "kuwait",
        "kyrgyzstan",
        "latvia",
        "lebanon",
        "lesotho",
        "liberia",
        "libya",
        "liechtenstein",
        "lithuania",
        "luxembourg",
        "madagascar",
        "malawi",
        "malaysia",
        "maldives",
        "mali",
        "malta",
        "mauritania",
        "mauritius",
        "mexico",
        "moldova",
        "monaco",
        "mongolia",
        "montenegro",
        "morocco",
        "mozambique",
        "myanmar",
        "namibia",
        "nepal",
        "netherlands",
        "new zealand",
        "nicaragua",
        "niger",
        "nigeria",
        "north korea",
        "north macedonia",
        "norway",
        "oman",
        "pakistan",
        "panama",
        "papua new guinea",
        "paraguay",
        "peru",
        "philippines",
        "poland",
        "portugal",
        "qatar",
        "romania",
        "russia",
        "rwanda",
        "saudi arabia",
        "senegal",
        "serbia",
        "singapore",
        "slovakia",
        "slovenia",
        "somalia",
        "south africa",
        "south korea",
        "south sudan",
        "spain",
        "sri lanka",
        "sudan",
        "sweden",
        "switzerland",
        "syria",
        "taiwan",
        "tajikistan",
        "tanzania",
        "thailand",
        "togo",
        "trinidad and tobago",
        "tunisia",
        "turkey",
        "turkmenistan",
        "uganda",
        "ukraine",
        "united arab emirates",
        "united kingdom",
        "united states",
        "uruguay",
        "uzbekistan",
        "venezuela",
        "vietnam",
        "yemen",
        "zambia",
        "zimbabwe"
      ]
    },
    "auto_parameters": {
      "type": "boolean",
      "default": false,
      "description": "쿼리 콘텐츠에 따라 검색 매개변수를 자동으로 구성합니다."
    },
    "include_usage": {
      "type": "boolean",
      "default": false,
      "description": "응답에 리소스 사용 정보를 포함합니다. 이는 Felo 청구 정보가 아닙니다."
    }
  },
  "required": [
    "query"
  ]
}
```

Example:

```json
{
  "query": "Python official documentation",
  "search_depth": "basic",
  "max_results": 2,
  "include_usage": true
}
```

## Responses

### 200 — 검색 결과가 성공적으로 반환되었습니다.

Headers:
- `X-Request-Id` (string) — Felo 지원팀에 문의할 때 포함할 요청 식별자입니다.

**application/json**

Schema: object

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "실행된 검색 쿼리입니다."
    },
    "answer": {
      "type": [
        "string",
        "null"
      ],
      "description": "LLM이 생성한 짧은 답변입니다. include_answer가 false이거나 답변이 생성되지 않으면 null로 표시됩니다."
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "이미지 URL입니다."
          },
          "description": {
            "type": "string",
            "description": "이미지 설명입니다."
          }
        }
      }
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "검색 결과의 제목입니다."
          },
          "url": {
            "type": "string",
            "description": "검색 결과의 URL입니다."
          },
          "content": {
            "type": "string",
            "description": "검색 결과의 콘텐츠 스니펫입니다."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "검색 결과의 관련성 점수입니다."
          },
          "favicon": {
            "type": [
              "string",
              "null"
            ],
            "description": "검색 결과의 파비콘 URL입니다."
          },
          "raw_content": {
            "type": [
              "string",
              "null"
            ],
            "description": "정제 및 파싱된 소스 콘텐츠입니다. include_raw_content를 요청하지 않았거나 원시 콘텐츠를 사용할 수 없으면 null입니다."
          }
        }
      }
    },
    "response_time": {
      "type": "number",
      "format": "float",
      "description": "요청을 완료하는 데 걸린 시간(초)입니다."
    },
    "usage": {
      "type": "object",
      "properties": {
        "credits": {
          "type": "integer",
          "description": "이 요청에서 소비된 리소스 단위이며 USD나 Felo 크레딧이 아닙니다."
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "고유 요청 식별자입니다."
    }
  }
}
```

Example:

```json
{
  "query": "Python official documentation",
  "answer": null,
  "images": [],
  "results": [
    {
      "title": "Python Documentation",
      "url": "https://docs.python.org/3/",
      "content": "Documentation for the Python programming language.",
      "score": 0.98,
      "raw_content": null
    }
  ],
  "response_time": 1.2,
  "usage": {
    "credits": 1
  },
  "request_id": "example-search-request"
}
```

### 400 — 요청을 처리할 수 없습니다. 요청 매개변수를 확인하세요.

### 401 — 유효한 Felo API 키가 필요합니다.

### 402 — 청구 요건이 충족되지 않아 요청을 진행할 수 없습니다.

### 403 — 이 계정에는 이 작업을 수행할 권한이 없습니다.

### 429 — 요청 또는 지출 한도에 도달했습니다.

### 502 — 서비스가 요청을 완료할 수 없습니다.

### 503 — API 또는 청구 서비스를 일시적으로 사용할 수 없습니다.

### 504 — 요청을 처리하는 동안 서비스 시간이 초과되었습니다.

### default — 오류 응답. 업스트림 패스스루 응답은 공급자 형식을 사용할 수 있습니다.

**application/json**

Schema:

```json
{}
```