> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factagora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fact Search

> 전 세계 출처에서 최근 뉴스 기사 검색

GNews와 네이버 뉴스를 포함한 전 세계 뉴스 출처에서 최근 기사를 검색합니다. 기사 제목, URL, 게재일, 출처 도메인을 반환합니다.

## 쿼리 파라미터

<ParamField query="q" type="string" required>
  뉴스 기사 검색 쿼리. 정확한 결과를 얻으려면 핵심 키워드를 사용하세요.
</ParamField>

<ParamField query="limit" type="number" default="10">
  반환할 결과의 최대 개수. 범위: 1–50.
</ParamField>

<ParamField query="language" type="string">
  출처 언어로 필터링. 예: `english`, `korean`
</ParamField>

<ParamField query="country" type="string">
  출처 국가 코드로 필터링. 예: `US`, `KR`
</ParamField>

<ParamField query="sortBy" type="string" default="relevance">
  정렬 순서. 옵션: `relevance`, `date`
</ParamField>

<ParamField query="timespan" type="string">
  상대 시간 범위 필터. 예: `7d`, `30d`, `3months`. `from` 또는 `to`가 지정되면 무시됩니다.
</ParamField>

<ParamField query="from" type="string">
  날짜 범위 시작 (ISO 8601). 지정 시 `timespan`보다 우선합니다. 예: `2025-01-01T00:00:00Z`
</ParamField>

<ParamField query="to" type="string">
  날짜 범위 종료 (ISO 8601). 지정 시 `timespan`보다 우선합니다. 예: `2025-05-01T23:59:59Z`
</ParamField>

<ParamField query="domains" type="string">
  포함할 출처 도메인 목록 (쉼표 구분). 해당 도메인의 기사만 반환합니다. 예: `bbc.com,reuters.com`
</ParamField>

<ParamField query="source" type="string" default="default">
  검색할 데이터 출처. 옵션:

  * `default`: 공개 뉴스 소스만 검색합니다. 기본값이며 기존 동작과 동일합니다.
  * `ingest`: 개인 수집 지식 베이스만 검색합니다. 개인 액세스 토큰이 필요합니다.
  * `all`: 뉴스와 개인 수집 지식 베이스를 합산하여 검색합니다. 개인 액세스 토큰이 필요합니다.
</ParamField>

## 응답

<ResponseField name="query" type="string">
  사용된 검색 쿼리입니다.
</ResponseField>

<ResponseField name="articles" type="array">
  뉴스 기사 목록입니다.

  <Expandable title="Article fields">
    <ResponseField name="title" type="string">기사 제목</ResponseField>
    <ResponseField name="url" type="string">기사 URL</ResponseField>
    <ResponseField name="domain" type="string">출처 도메인</ResponseField>
    <ResponseField name="publishedAt" type="string">게재 일시 (ISO 8601)</ResponseField>
    <ResponseField name="language" type="string">기사 언어</ResponseField>
    <ResponseField name="sourceCountry" type="string">출처 국가 코드</ResponseField>
    <ResponseField name="snippet" type="string">기사 발췌 (선택)</ResponseField>
    <ResponseField name="imageUrl" type="string">기사 이미지 URL (선택)</ResponseField>
    <ResponseField name="source" type="string">`gnews` 또는 `naver`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Meta fields">
    <ResponseField name="total" type="number">전체 결과 수</ResponseField>
    <ResponseField name="executionTimeMs" type="number">응답 시간(밀리초)</ResponseField>
    <ResponseField name="source" type="string">사용된 데이터 출처 (`gnews`, `naver`, `mixed`)</ResponseField>
    <ResponseField name="cached" type="boolean">캐시에서 응답되었는지 여부</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.factagora.com/api/v1/fact-search?q=bitcoin&limit=5&language=english" \
    -H "Authorization: Bearer fag_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "query": "bitcoin",
    "articles": [
      {
        "title": "Bitcoin surges past $100,000 amid institutional demand",
        "url": "https://reuters.com/...",
        "domain": "reuters.com",
        "publishedAt": "2026-03-29T10:00:00Z",
        "language": "english",
        "sourceCountry": "US",
        "snippet": "Bitcoin hit a new all-time high as institutional investors...",
        "source": "gnews"
      }
    ],
    "meta": {
      "total": 1,
      "executionTimeMs": 312,
      "source": "gnews",
      "cached": false
    }
  }
  ```
</ResponseExample>