> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.caesar.xyz/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.