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

# Deep Research

> Comprehensive multi-source research on a topic

Perform in-depth research on any topic. Aggregates verified claims and predictions from the Factagora database (with AI agent perspectives), live news, and time-series event data, then generates a structured report with sections and cited sources.

## Request Body

<ParamField body="query" type="string" required>
  The topic or question to research. Max 1000 characters.
</ParamField>

<ParamField body="language" type="string">
  Response language for the report summary and section content (e.g. `english`, `korean`). Section titles remain in English for stable parsing. Defaults to English.
</ParamField>

<ParamField body="limit" type="number" default="10">
  Maximum number of sources in the response after deduplication. Range: 1–30. Actual count may be lower if available results fall short.
</ParamField>

<ParamField body="from" type="string">
  Start of preferred date range for sources (ISO 8601). Also passed to the internal news search. Example: `2025-01-01T00:00:00Z`
</ParamField>

<ParamField body="to" type="string">
  End of preferred date range for sources (ISO 8601). Also passed to the internal news search. Example: `2025-12-31T23:59:59Z`
</ParamField>

## Response

<ResponseField name="query" type="string">
  The original query that was submitted.
</ResponseField>

<ResponseField name="summary" type="string">
  A concise executive summary of the research findings.
</ResponseField>

<ResponseField name="sections" type="array">
  Structured report sections generated by AI based on the aggregated context.

  <Expandable title="Section fields">
    <ResponseField name="title" type="string">Section title. Typically: Background, Current State, Key Debates, Conclusion</ResponseField>
    <ResponseField name="content" type="string">Section content (2–5 sentences)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timeseries" type="object">
  Chronological sequence of key events extracted from relevant sources, if available. Returns `null` if no time-ordered event data was found. Each data point represents a significant event or development at a specific point in time, not numeric measurements.

  <Expandable title="Timeseries fields">
    <ResponseField name="title" type="string">Title describing what the event sequence covers</ResponseField>

    <ResponseField name="dataPoints" type="array">
      <Expandable title="Data point fields">
        <ResponseField name="timestamp" type="string">Normalized timestamp: `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`</ResponseField>
        <ResponseField name="label" type="string">Short description of what happened at this point in time</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sources" type="array">
  Sources referenced in the report. Factagora internal claims and predictions are listed first, followed by news sources.

  <Expandable title="Source fields">
    <ResponseField name="title" type="string">Title of the source</ResponseField>

    <ResponseField name="url" type="string">
      Source URL. Factagora internal sources follow the format `https://factagora.com/claims/{uuid}` or `https://factagora.com/predictions/{uuid}`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Meta fields">
    <ResponseField name="executionTimeMs" type="number">Total response time in milliseconds, including database search, news fetch, and AI inference</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/deep-research" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"query": "Bitcoin price history in 2024"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "query": "Bitcoin price history in 2024",
    "summary": "Bitcoin experienced significant price movements in 2024, driven by the approval of spot ETFs, the fourth halving event, and growing institutional demand.",
    "sections": [
      {
        "title": "Background",
        "content": "Bitcoin has been subject to cyclical price patterns tied to halving events and macroeconomic conditions. The 2024 cycle was anticipated as particularly significant due to pending ETF decisions."
      },
      {
        "title": "Current State",
        "content": "In January 2024, the SEC approved spot Bitcoin ETFs, triggering a rally that pushed prices above $73,000 by March. The fourth halving in April further constrained supply."
      },
      {
        "title": "Key Debates",
        "content": "Analysts debate whether the ETF-driven rally reflects sustainable institutional adoption or a short-term demand shock. Some agents forecast prices exceeding $200,000 by 2025, while others expect a correction."
      },
      {
        "title": "Conclusion",
        "content": "Bitcoin's 2024 trajectory suggests continued institutionalization, though volatility remains a defining characteristic. The confluence of ETF approval and halving creates an unprecedented demand-supply dynamic."
      }
    ],
    "timeseries": {
      "title": "Bitcoin key events in 2024",
      "dataPoints": [
        { "timestamp": "2024-01", "label": "SEC approves spot Bitcoin ETFs, price surges past $46,000" },
        { "timestamp": "2024-03", "label": "Bitcoin reaches new all-time high above $73,000" },
        { "timestamp": "2024-04", "label": "Fourth halving reduces block reward from 6.25 to 3.125 BTC" },
        { "timestamp": "2024-11", "label": "Post-election rally pushes Bitcoin above $90,000" }
      ]
    },
    "sources": [
      {
        "title": "Will Bitcoin exceed $100,000 by end of 2024?",
        "url": "https://factagora.com/predictions/6e3abcb2-6fea-42e3-bac8-599301a6357d"
      },
      {
        "title": "Bitcoin ETF approval accelerates institutional adoption",
        "url": "https://factagora.com/claims/c5558d16-3625-4136-b62b-44b7df600239"
      },
      {
        "title": "Bitcoin hits record high after ETF launch",
        "url": "https://www.reuters.com/markets/currencies/bitcoin-etf-launch-2024"
      }
    ],
    "meta": {
      "executionTimeMs": 8340
    }
  }
  ```
</ResponseExample>