Response Models

BatchResearchResponse

The BatchResearchResponse model contains the complete results of a batch research operation, including all findings, evidence, performance metrics, and metadata.

Model Definition

from typing import List
from pydantic import BaseModel, Field

class BatchResearchResponse(BaseModel):
    research_id: str
    total_companies: int
    search_strategies_generated: int
    total_searches_executed: int
    processing_time_ms: int
    results: List[CompanyResearchResult]
    search_performance: SearchPerformance

Fields

research_id

string

required

Unique identifier for this research operation. Use this ID for tracking, logging, and debugging.Format: UUID v4 stringExample: "550e8400-e29b-41d4-a716-446655440000"

total_companies

integer

required

Total number of companies analyzed in this batch research operation.Example: 25

search_strategies_generated

integer

required

Number of search strategies generated based on the research goal and search depth.Typical ranges:

Quick: 5-10 strategies
Standard: 15-25 strategies
Comprehensive: 30-50 strategies

Example: 18

total_searches_executed

integer

required

Total number of individual search queries executed across all companies and strategies.Calculation: number_of_strategies × number_of_companiesExample: 450 (18 strategies × 25 companies)

processing_time_ms

integer

required

Total processing time in milliseconds from request initiation to response completion.Example: 12500 (12.5 seconds)

results

array

required

Array of research results, one for each company analyzed.Type: List[CompanyResearchResult]See CompanyResearchResult below for details.

search_performance

object

required

Performance metrics for the search operation.Type: SearchPerformanceSee SearchPerformance below for details.

CompanyResearchResult

Detailed research results for a single company, including confidence score, evidence, and findings.

Model Definition

from typing import List
from pydantic import BaseModel

class CompanyResearchResult(BaseModel):
    domain: str
    confidence_score: float
    evidence_sources: int
    findings: Findings

Fields

domain

string

required

The company domain that was analyzed.Example: "stripe.com"

confidence_score

float

required

Overall confidence score (0.0-1.0) representing the reliability of the findings for this company.Range: 0.0 (no confidence) to 1.0 (absolute confidence)Interpretation:

0.0-0.3: Low confidence, limited evidence
0.3-0.7: Moderate confidence, some supporting evidence
0.7-1.0: High confidence, strong evidence

Example: 0.85

evidence_sources

integer

required

Number of unique evidence sources found for this company.Example: 12

findings

object

required

Detailed findings including technologies identified and supporting evidence.Type: FindingsSee Findings below for details.

Findings

Contains the actual research findings including identified technologies and supporting evidence.

Model Definition

from typing import List
from pydantic import BaseModel, Field

class Findings(BaseModel):
    technologies: List[str] = Field(default_factory=list)
    evidence: List[Evidence] = Field(default_factory=list)
    signals_found: int = 0

Fields

technologies

array

required

List of technologies, tools, or signals identified for this company.Type: List[str]Default: [] (empty list)Example: ["React", "TypeScript", "Node.js", "PostgreSQL"]

evidence

array

required

Array of evidence items supporting the findings.Type: List[Evidence]Default: [] (empty list)See Evidence below for details.

signals_found

integer

required

Total number of signals or indicators found across all evidence sources.Default: 0Example: 27

Evidence

Represents a single piece of evidence supporting the research findings.

Model Definition

from pydantic import BaseModel

class Evidence(BaseModel):
    url: str
    title: str
    snippet: str
    source_name: str

Fields

url

string

required

URL of the evidence source.Example: "https://stripe.com/jobs/engineering"

title

string

required

Title of the evidence source (e.g., page title, article headline).Example: "Senior Backend Engineer - Payments Platform"

snippet

string

required

Relevant text snippet extracted from the source that supports the finding.Example:

"We're looking for engineers experienced with React, TypeScript, and Node.js to build our next-generation payment infrastructure."

source_name

string

required

Name or identifier of the search channel that provided this evidence.Example values:

"web_search"
"jobs_search"
"news_search"
"social_search"

SearchPerformance

Performance metrics for the search operation.

Model Definition

from pydantic import BaseModel

class SearchPerformance(BaseModel):
    queries_per_second: float
    failed_requests: int

Fields

queries_per_second

float

required

Average number of search queries executed per second during the operation.Example: 15.7

failed_requests

integer

required

Total number of search requests that failed due to errors, timeouts, or rate limiting.Example: 3

Complete Example Response

JSON
Python

{
  "research_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_companies": 3,
  "search_strategies_generated": 15,
  "total_searches_executed": 45,
  "processing_time_ms": 8750,
  "results": [
    {
      "domain": "stripe.com",
      "confidence_score": 0.92,
      "evidence_sources": 18,
      "findings": {
        "technologies": [
          "React",
          "TypeScript",
          "Node.js",
          "Ruby",
          "PostgreSQL",
          "Redis"
        ],
        "evidence": [
          {
            "url": "https://stripe.com/jobs/listing/senior-frontend-engineer",
            "title": "Senior Frontend Engineer - Dashboard",
            "snippet": "We're seeking engineers with deep experience in React and TypeScript to build the next generation of our developer dashboard.",
            "source_name": "jobs_search"
          },
          {
            "url": "https://stripe.com/blog/engineering-culture",
            "title": "How We Build at Stripe",
            "snippet": "Our infrastructure runs on Ruby and Node.js services, with PostgreSQL and Redis for data storage.",
            "source_name": "web_search"
          }
        ],
        "signals_found": 34
      }
    },
    {
      "domain": "shopify.com",
      "confidence_score": 0.88,
      "evidence_sources": 15,
      "findings": {
        "technologies": [
          "React",
          "TypeScript",
          "GraphQL",
          "Ruby on Rails",
          "MySQL"
        ],
        "evidence": [
          {
            "url": "https://shopify.engineering/building-admin-graphql-api",
            "title": "Building Shopify's GraphQL API",
            "snippet": "We rebuilt our Admin API using GraphQL, with a React and TypeScript frontend.",
            "source_name": "web_search"
          }
        ],
        "signals_found": 28
      }
    },
    {
      "domain": "square.com",
      "confidence_score": 0.76,
      "evidence_sources": 11,
      "findings": {
        "technologies": [
          "React",
          "Java",
          "Kotlin",
          "MySQL"
        ],
        "evidence": [
          {
            "url": "https://developer.squareup.com/blog/technology-stack",
            "title": "Square's Technology Stack",
            "snippet": "Our web applications are built with React, while our backend services use Java and Kotlin.",
            "source_name": "web_search"
          }
        ],
        "signals_found": 19
      }
    }
  ],
  "search_performance": {
    "queries_per_second": 12.4,
    "failed_requests": 2
  }
}

from app.models import BatchResearchResponse
import httpx

async def analyze_companies():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.example.com/research/batch",
            json={
                "research_goal": "Find companies using React and TypeScript",
                "company_domains": ["stripe.com", "shopify.com", "square.com"],
                "search_depth": "standard",
                "max_parallel_searches": 25,
                "confidence_threshold": 0.6
            }
        )
        
        # Parse response into BatchResearchResponse model
        result: BatchResearchResponse = BatchResearchResponse(**response.json())
        
        # Access results
        print(f"Research ID: {result.research_id}")
        print(f"Processing time: {result.processing_time_ms}ms")
        print(f"Companies analyzed: {result.total_companies}")
        
        # Iterate through company results
        for company_result in result.results:
            print(f"\n{company_result.domain}:")
            print(f"  Confidence: {company_result.confidence_score:.2f}")
            print(f"  Technologies: {', '.join(company_result.findings.technologies)}")
            print(f"  Evidence sources: {company_result.evidence_sources}")
            
            # Show first evidence item
            if company_result.findings.evidence:
                first_evidence = company_result.findings.evidence[0]
                print(f"  Sample evidence: {first_evidence.title}")

Usage Patterns

Filtering High-Confidence Results

from app.models import BatchResearchResponse

def filter_high_confidence(response: BatchResearchResponse, min_confidence: float = 0.8):
    """Filter results to only include high-confidence findings."""
    return [
        result for result in response.results 
        if result.confidence_score >= min_confidence
    ]

# Usage
high_confidence_results = filter_high_confidence(response, min_confidence=0.8)
print(f"Found {len(high_confidence_results)} high-confidence results")

Extracting All Technologies

from typing import Set
from app.models import BatchResearchResponse

def extract_all_technologies(response: BatchResearchResponse) -> Set[str]:
    """Extract unique set of all technologies found across all companies."""
    technologies = set()
    for result in response.results:
        technologies.update(result.findings.technologies)
    return technologies

# Usage
all_techs = extract_all_technologies(response)
print(f"Technologies found: {', '.join(sorted(all_techs))}")

Analyzing Evidence Quality

from app.models import BatchResearchResponse

def analyze_evidence_quality(response: BatchResearchResponse):
    """Analyze the distribution of evidence sources."""
    for result in response.results:
        evidence_count = len(result.findings.evidence)
        avg_confidence = result.confidence_score
        
        print(f"{result.domain}:")
        print(f"  Evidence items: {evidence_count}")
        print(f"  Confidence: {avg_confidence:.2%}")
        print(f"  Evidence per signal: {evidence_count / max(result.findings.signals_found, 1):.2f}")

Performance Analysis

from app.models import BatchResearchResponse

def analyze_performance(response: BatchResearchResponse):
    """Analyze search performance metrics."""
    perf = response.search_performance
    
    success_rate = (
        (response.total_searches_executed - perf.failed_requests) 
        / response.total_searches_executed * 100
    )
    
    avg_time_per_search = (
        response.processing_time_ms / response.total_searches_executed
    )
    
    print(f"Performance Metrics:")
    print(f"  Total searches: {response.total_searches_executed}")
    print(f"  Success rate: {success_rate:.1f}%")
    print(f"  Queries/second: {perf.queries_per_second:.1f}")
    print(f"  Avg time per search: {avg_time_per_search:.0f}ms")
    print(f"  Failed requests: {perf.failed_requests}")

Best Practices

Show Interpreting Confidence Scores

Confidence scores are calculated based on multiple factors including:

Number of evidence sources found
Relevance of evidence to the research goal
Consistency across different search channels
Quality and recency of sources

Always review the actual evidence items, not just the confidence score, when making critical decisions.

Show Handling Large Result Sets

For batch operations with many companies:

Process results incrementally rather than loading everything into memory
Filter results early based on confidence threshold
Consider using the streaming endpoint for real-time processing
Store results in a database for later analysis

Show Evidence Deduplication

The engine automatically deduplicates evidence based on URL and content similarity. However, you may want to implement additional deduplication logic if:

Multiple search channels return the same content from different URLs
You’re combining results from multiple research operations
You need domain-specific deduplication rules

Show Monitoring Performance

Key metrics to monitor:

failed_requests: Should be < 5% of total searches
queries_per_second: Should match your expected throughput
processing_time_ms: Should scale linearly with company count and search depth

If you see degraded performance, consider:

Reducing max_parallel_searches
Using a lower search_depth
Implementing request batching

BatchResearchRequest - Request model for batch research operations
QueryStrategy - Search strategy model used to generate queries

Endpoints

Models

BatchResearchResponse

Model Definition

Fields

CompanyResearchResult

Model Definition

Fields

Findings

Model Definition

Fields

Evidence

Model Definition

Fields

SearchPerformance

Model Definition

Fields

Complete Example Response

Usage Patterns

Filtering High-Confidence Results

Extracting All Technologies

Analyzing Evidence Quality

Performance Analysis

Best Practices

Build docs developers (and LLMs) love

Endpoints

Models

​BatchResearchResponse

​Model Definition

​Fields

​CompanyResearchResult

​Model Definition

​Fields

​Findings

​Model Definition

​Fields

​Evidence

​Model Definition

​Fields

​SearchPerformance

​Model Definition

​Fields

​Complete Example Response

​Usage Patterns

​Filtering High-Confidence Results

​Extracting All Technologies

​Analyzing Evidence Quality

​Performance Analysis

​Best Practices

​Related Models

Build docs developers (and LLMs) love

BatchResearchResponse

Model Definition

Fields

CompanyResearchResult

Model Definition

Fields

Findings

Model Definition

Fields

Evidence

Model Definition

Fields

SearchPerformance

Model Definition

Fields

Complete Example Response

Usage Patterns

Filtering High-Confidence Results

Extracting All Technologies

Analyzing Evidence Quality

Performance Analysis

Best Practices

Related Models