Request Models

BatchResearchRequest

The BatchResearchRequest model defines the input parameters for batch research operations. It allows you to analyze multiple companies simultaneously with customizable search strategies and confidence thresholds.

Model Definition

from typing import List, Literal
from pydantic import BaseModel, Field

class BatchResearchRequest(BaseModel):
    research_goal: str = Field(..., description="The high-level research objective")
    company_domains: List[str] = Field(..., description="Company domains to analyze")
    search_depth: Literal["quick", "standard", "comprehensive"] = Field(
        ..., 
        description="Controls the number of strategies and search breadth",
    )
    max_parallel_searches: int = Field(
        ..., description="Overrides default global concurrency if provided"
    )
    confidence_threshold: float = Field(
        ...,
        ge=0.0, 
        le=1.0, 
        description="Threshold to include a finding in results"
    )

Fields

research_goal

string

required

The high-level research objective that guides the search strategy generation. This should be a clear, specific description of what information you’re looking for.Example values:

"Find companies using Salesforce for CRM"
"Identify e-commerce platforms built with React"
"Discover companies hiring for AI/ML positions"

company_domains

array

required

List of company domains to analyze. Each domain should be a valid web domain without protocol prefix.Type: List[str]Example: ["stripe.com", "shopify.com", "square.com"]

search_depth

enum

required

Controls the number of search strategies generated and the breadth of the search.Allowed values:

"quick" - Fast search with fewer strategies (recommended for exploratory analysis)
"standard" - Balanced search depth and speed (recommended for most use cases)
"comprehensive" - Exhaustive search with maximum strategies (recommended for critical research)

Performance impact:

Quick: ~5-10 strategies, completes in seconds
Standard: ~15-25 strategies, completes in tens of seconds
Comprehensive: ~30-50 strategies, completes in minutes

max_parallel_searches

integer

required

Maximum number of concurrent search operations. Higher values increase speed but consume more resources.Constraints: Must be a positive integerRecommended values:

Development/testing: 5-10
Production with rate limits: 20-50
High-performance: 50-100

Note: This overrides the default global concurrency setting. Consider your API rate limits and server capacity when setting this value.

confidence_threshold

float

required

Minimum confidence score (0.0-1.0) required to include a finding in the results. Higher thresholds return more precise but fewer results.Constraints:

Minimum: 0.0 (include all findings)
Maximum: 1.0 (only perfect matches)

Recommended values:

Exploratory research: 0.3-0.5
Standard research: 0.5-0.7
High-precision research: 0.7-0.9

Example Request

Python
JSON
cURL

from app.models import BatchResearchRequest

request = BatchResearchRequest(
    research_goal="Find companies using React and TypeScript",
    company_domains=[
        "airbnb.com",
        "netflix.com",
        "uber.com"
    ],
    search_depth="standard",
    max_parallel_searches=25,
    confidence_threshold=0.6
)

{
  "research_goal": "Find companies using React and TypeScript",
  "company_domains": [
    "airbnb.com",
    "netflix.com",
    "uber.com"
  ],
  "search_depth": "standard",
  "max_parallel_searches": 25,
  "confidence_threshold": 0.6
}

curl -X POST "https://api.example.com/research/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "research_goal": "Find companies using React and TypeScript",
    "company_domains": ["airbnb.com", "netflix.com", "uber.com"],
    "search_depth": "standard",
    "max_parallel_searches": 25,
    "confidence_threshold": 0.6
  }'

Validation Rules

The model enforces the following validation rules:

research_goal: Required, non-empty string
company_domains: Required, must contain at least one domain
search_depth: Must be exactly one of: "quick", "standard", or "comprehensive"
max_parallel_searches: Required positive integer
confidence_threshold: Required float between 0.0 and 1.0 (inclusive)

Usage Example

Here’s how the request model is used in the API endpoint:

from fastapi import APIRouter
from app.models import BatchResearchRequest, BatchResearchResponse

router = APIRouter()

@router.post("/research/batch", response_model=BatchResearchResponse)
async def research_batch(payload: BatchResearchRequest) -> BatchResearchResponse:
    # The payload is automatically validated against BatchResearchRequest
    query_generator = QueryGenerator()
    strategies = await query_generator.generate_strategies(
        research_goal=payload.research_goal,
        search_depth=payload.search_depth,
    )
    
    pipeline = ResearchPipeline(
        research_goal=payload.research_goal,
        search_depth=payload.search_depth,
        company_domains=payload.company_domains,
        strategies=strategies,
        max_parallel_searches=payload.max_parallel_searches,
        confidence_threshold=payload.confidence_threshold,
    )
    
    results = await pipeline.run()
    return results

Best Practices

Show Choosing the Right Search Depth

Quick: Use for rapid prototyping, testing, or when you need fast results with acceptable accuracy
Standard: The default choice for most production use cases, balancing speed and comprehensiveness
Comprehensive: Use when accuracy is critical and processing time is not a constraint

Show Setting Confidence Thresholds

Start with a lower threshold (0.4-0.5) and analyze the quality of results. If you’re getting too many false positives, increase the threshold incrementally. If you’re missing expected results, lower the threshold.

Show Optimizing Parallel Searches

Monitor your search provider’s rate limits and adjust max_parallel_searches accordingly. Setting this too high may result in throttling or failed requests. A good starting point is 25-30 for most APIs.

Show Writing Effective Research Goals

Be specific and include the key technologies, signals, or patterns you’re looking for. Good research goals lead to better search strategy generation.Good examples:

“Identify companies using Kubernetes in production”
“Find SaaS companies with open engineering positions in AI/ML”

Poor examples:

“Research companies” (too vague)
“Tech stack” (no specific technology mentioned)

BatchResearchResponse - The response model returned by batch research endpoints
QueryStrategy - Search strategy model used internally by the engine

Endpoints

Models

BatchResearchRequest

Model Definition

Fields

Example Request

Validation Rules

Usage Example

Best Practices

Build docs developers (and LLMs) love

Endpoints

Models

​BatchResearchRequest

​Model Definition

​Fields

​Example Request

​Validation Rules

​Usage Example

​Best Practices

​Related Models

Build docs developers (and LLMs) love

BatchResearchRequest

Model Definition

Fields

Example Request

Validation Rules

Usage Example

Best Practices

Related Models