> ## 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

> Search recent news articles from global sources

Search recent news articles from global news sources including GNews and Naver News. Returns article titles, URLs, publication dates, and source domains.

## Query Parameters

<ParamField query="q" type="string" required>
  Search query for news articles. Use focused keywords for best results.
</ParamField>

<ParamField query="limit" type="number" default="10">
  Maximum number of results to return. Range: 1–50.
</ParamField>

<ParamField query="language" type="string">
  Filter by source language. Examples: `english`, `korean`
</ParamField>

<ParamField query="country" type="string">
  Filter by source country code. Examples: `US`, `KR`
</ParamField>

<ParamField query="sortBy" type="string" default="relevance">
  Sort order. Options: `relevance`, `date`
</ParamField>

<ParamField query="timespan" type="string">
  Relative time range filter. Examples: `7d`, `30d`, `3months`. Ignored when `from` or `to` is provided.
</ParamField>

<ParamField query="from" type="string">
  Start of date range (ISO 8601). Takes precedence over `timespan` when set. Example: `2025-01-01T00:00:00Z`
</ParamField>

<ParamField query="to" type="string">
  End of date range (ISO 8601). Takes precedence over `timespan` when set. Example: `2025-05-01T23:59:59Z`
</ParamField>

<ParamField query="domains" type="string">
  Comma-separated list of source domains to include. Only articles from these domains are returned. Example: `bbc.com,reuters.com`
</ParamField>

<ParamField query="source" type="string" default="default">
  Data source to search. Options:

  * `default`: public news sources only (default)
  * `ingest`: personal ingested knowledge base only (requires personal access token)
  * `all`: news + personal ingested knowledge base combined (requires personal access token)
</ParamField>

## Response

<ResponseField name="query" type="string">
  The search query that was used.
</ResponseField>

<ResponseField name="articles" type="array">
  List of news articles.

  <Expandable title="Article fields">
    <ResponseField name="title" type="string">Article title</ResponseField>
    <ResponseField name="url" type="string">Article URL</ResponseField>
    <ResponseField name="domain" type="string">Source domain</ResponseField>
    <ResponseField name="publishedAt" type="string">Publication datetime (ISO 8601)</ResponseField>
    <ResponseField name="language" type="string">Article language</ResponseField>
    <ResponseField name="sourceCountry" type="string">Source country code</ResponseField>
    <ResponseField name="snippet" type="string">Article excerpt (optional)</ResponseField>
    <ResponseField name="imageUrl" type="string">Article image URL (optional)</ResponseField>
    <ResponseField name="source" type="string">`gnews` or `naver`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Meta fields">
    <ResponseField name="total" type="number">Total number of results</ResponseField>
    <ResponseField name="executionTimeMs" type="number">Response time in milliseconds</ResponseField>
    <ResponseField name="source" type="string">Data source used (`gnews`, `naver`, `mixed`)</ResponseField>
    <ResponseField name="cached" type="boolean">Whether the response was served from cache</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>