> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caesar.xyz/2025-11-27/documentation/guides/research-parameters/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# Research Parameters

Caesar's research API provides several parameters to control the depth, speed, and nature of your research queries. Understanding these parameters helps you balance thoroughness, response time, and cost.

> **Tip**
>
> New to Caesar? Start with `auto: true` to let the system intelligently configure parameters based on your query.

## Parameter overview

| Parameter          | Type    | Default | Description                         |
| ------------------ | ------- | ------- | ----------------------------------- |
| `collection_ids`   | array   | -       | Collection IDs to search across     |
| `reasoning_loops`  | integer | 1       | Maximum reasoning iterations (1-10) |
| `source_timeout`   | integer | 60      | Seconds to wait per source (3-180)  |
| `reasoning_mode`   | boolean | false   | Use advanced reasoning models       |
| `allow_early_exit` | boolean | false   | Allow completion before max loops   |
| `exclude_social`   | boolean | false   | Exclude social media sources        |
| `auto`             | boolean | false   | Auto-configure based on query       |

---

## collection\_ids

Specifies one or more file collections to include in the research. When provided, the research pipeline will search across all files within the specified collections, enabling RAG-style queries over your uploaded documents.

```json
{
  "query": "Summarize the key findings from my research papers",
  "collection_ids": ["a1b2c3d4-5678-90ab-cdef-1234567890ab"]
}
```

### When to use collections

#### With collections

**Use when:**

* You have organized documents into thematic collections
* You want to research across multiple related files
* You need answers grounded in your uploaded content

**Example:** Research across all quarterly reports in your "Financial Reports" collection

#### With individual files

**Use when:**

* You want to analyze specific documents
* You have a small number of files to include
* Files aren't organized into collections

**Example:** Analyze a single contract or research paper

> **Info**
>
> You can combine `collection_ids` with `files` to include both collection-based and individual file sources in a single research request.

---

## reasoning\_loops

Controls the maximum number of iterative reasoning cycles Caesar performs. Each loop involves gathering information, analyzing findings, identifying gaps, and refining the response.

```json
{
  "query": "What are the implications of quantum computing for cryptography?",
  "reasoning_loops": 3
}
```

### How it works

During each reasoning loop, Caesar:

#### Generates search queries

Creates targeted queries based on the research question and current knowledge gaps.

#### Gathers information

Retrieves and processes content from diverse sources.

#### Evaluates completeness

Assesses whether sufficient information has been gathered or if more research is needed.

#### Synthesizes findings

Integrates new information into a coherent understanding.

### Choosing the right value

| Loops    | Best for               | Example queries                                             |
| -------- | ---------------------- | ----------------------------------------------------------- |
| **1-2**  | Simple factual queries | "What is the capital of France?", "Apple stock price today" |
| **3-4**  | Comparative analysis   | "Compare React vs Vue for enterprise apps"                  |
| **5-6**  | Literature reviews     | "Recent advances in CRISPR gene editing"                    |
| **7-10** | Complex research       | "Systematic analysis of climate policy effectiveness"       |

> **Info**
>
> The response includes `reasoning_loops_consumed` showing how many loops were actually executed. With `allow_early_exit: true`, this may be less than the maximum.

### Performance impact

![Caesar performance on Humanity's Last Exam benchmark across reasoning loops](/_fern-img/cb55d9ba700afbe7399d6422d0423c80442bb242f5613e89ff9f019c5bb354f3.webp)

> **Note**
>
> Performance on Humanity's Last Exam (HLE) shows significant improvement from 1 to 3 loops (19.95% → 53.85%), with diminishing returns beyond 5 loops. The sweet spot for most queries is 2-4 loops.

---

## source\_timeout

Controls how long Caesar waits when fetching content from each source URL before moving on.

```json
{
  "query": "Analysis of recent SEC filings",
  "source_timeout": 90
}
```

### When to adjust

#### Lower timeout (3-30s)

**Use when:**

* Speed is critical
* Sources are generally fast
* You prefer partial results quickly

**Trade-off:** May miss slow-loading sources

#### Higher timeout (90-180s)

**Use when:**

* Completeness matters more than speed
* Researching slow institutional sources
* Academic or government databases

**Trade-off:** Longer response times

> **Warning**
>
> Very low timeouts (under 10s) may result in incomplete source processing. The default of 60 seconds works well for most use cases.

---

## reasoning\_mode

Enables advanced reasoning models for deeper analysis and synthesis.

```json
{
  "query": "Evaluate the economic implications of universal basic income",
  "reasoning_mode": true
}
```

### Standard vs Advanced mode

#### Standard (false)

* Uses optimized, faster models
* Lower latency responses
* Cost-efficient for straightforward queries
* Best for: factual lookups, simple summaries, news aggregation

#### Advanced (true)

* Uses frontier reasoning models
* Superior analytical capabilities
* Better handling of nuanced, multi-faceted questions
* Best for: complex analysis, technical research, strategic insights

### When to enable

| Query type               | Recommended |
| ------------------------ | ----------- |
| News summaries           | `false`     |
| Market data lookups      | `false`     |
| Technical comparisons    | `true`      |
| Strategic analysis       | `true`      |
| Research synthesis       | `true`      |
| Complex reasoning chains | `true`      |

---

## allow\_early\_exit

Permits the research process to complete before exhausting all reasoning loops if sufficient information has been gathered.

```json
{
  "query": "What is the current Bitcoin price?",
  "reasoning_loops": 5,
  "allow_early_exit": true
}
```

### How it works

When enabled, Caesar evaluates after each loop whether:

* The query has been sufficiently answered
* Additional research would be redundant
* All major perspectives have been considered

If these conditions are met, the process completes early, saving time and resources.

> **Tip**
>
> With `allow_early_exit: true`, a simple query set to 5 loops might complete in just 1-2 loops. Check `reasoning_loops_consumed` in the response to see actual usage.

### Comparison

| Setting | Behavior              | Best for                                  |
| ------- | --------------------- | ----------------------------------------- |
| `false` | Always runs all loops | Exhaustive research, maximum thoroughness |
| `true`  | Exits when sufficient | General queries, cost optimization        |

---

## exclude\_social

Excludes social media platforms (Twitter/X, YouTube) from search results.

```json
{
  "query": "Clinical trial results for new Alzheimer's treatment",
  "exclude_social": true
}
```

### When to use

#### Include social (false)

**Best for:**

* Sentiment analysis
* Trend identification
* Public opinion research
* Breaking news
* Community discussions

#### Exclude social (true)

**Best for:**

* Academic research
* Technical documentation
* Medical/scientific queries
* Financial analysis
* Legal research

---

## auto

Enables intelligent auto-configuration where Caesar analyzes your query and automatically determines optimal parameter values.

```json
{
  "query": "Compare the environmental impact of electric vehicles vs hydrogen fuel cells",
  "auto": true
}
```

### How auto mode works

When `auto: true`, Caesar:

1. **Analyzes the query** - Evaluates complexity, domain, and intent
2. **Classifies requirements** - Determines if the query needs deep reasoning, social sources, etc.
3. **Sets optimal parameters** - Configures all other parameters automatically

> **Info**
>
> When `auto: true`, explicit parameter values you provide are overridden by the auto-detected optimal settings.

### Auto mode defaults

If query classification succeeds, parameters are set based on analysis. If classification fails, sensible defaults are used:

| Parameter          | Auto fallback |
| ------------------ | ------------- |
| `reasoning_loops`  | 2             |
| `source_timeout`   | 30            |
| `reasoning_mode`   | true          |
| `allow_early_exit` | true          |
| `exclude_social`   | false         |

---

## Example configurations

#### Quick lookup

Fast response for simple queries:

```json
{
  "query": "What is the current market cap of Apple?",
  "reasoning_loops": 1,
  "source_timeout": 30,
  "reasoning_mode": false,
  "allow_early_exit": true
}
```

#### Balanced research

Good balance of depth and speed:

```json
{
  "query": "Recent developments in large language models",
  "reasoning_loops": 3,
  "source_timeout": 60,
  "reasoning_mode": true,
  "allow_early_exit": true
}
```

#### Deep analysis

Thorough research for complex topics:

```json
{
  "query": "Comprehensive analysis of global semiconductor supply chain vulnerabilities",
  "reasoning_loops": 7,
  "source_timeout": 120,
  "reasoning_mode": true,
  "allow_early_exit": false,
  "exclude_social": true
}
```

#### Auto mode

Let Caesar decide:

```json
{
  "query": "What are the pros and cons of remote work?",
  "auto": true
}
```

---

## Response fields

The research response includes fields that reflect parameter usage:

```json
{
  "id": "abc-123",
  "status": "completed",
  "reasoning_loops_consumed": 2,
  "running_time": 45,
  "content": "...",
  "results": [...]
}
```

| Field                      | Description                                                            |
| -------------------------- | ---------------------------------------------------------------------- |
| `reasoning_loops_consumed` | Actual number of loops executed (may be less than max with early exit) |
| `running_time`             | Total execution time in seconds                                        |

> **Info**
>
> **Usage is based on `reasoning_loops_consumed`**, not the `reasoning_loops` you request. This means only actual work performed counts toward your usage. If early exit completes a job in fewer loops, usage reflects that.

---

## Best practices

#### Start with auto

Use `auto: true` for your first queries. Review the results and fine-tune parameters only if needed.

#### Match complexity

Simple queries don't need high loop counts. Save resources by matching parameters to query complexity.

#### Consider your sources

Enable `exclude_social` for academic or technical research where authoritative sources matter.

#### Balance speed and depth

Use `allow_early_exit: true` with higher loop counts to get thoroughness when needed without wasting time on simple queries.

> **Warning**
>
> **Cost consideration:** Higher `reasoning_loops` and `reasoning_mode: true` consume more resources. Monitor your usage and optimize parameters for your specific needs.

> Fine-tune Caesar's research process for optimal results