Skip to content

Deep Research Batch

Request

Process multiple records for AI deep research in batch mode.

Overview

The Deep Research Batch API allows you to submit multiple records for AI-powered deep research processing asynchronously.

Key Differences from Sync API:

  • Sync API (/v1/enrich/research): Process one query at a time, get immediate response with research results
  • Batch API (/v1/agents/deep-research): Submit 1-1000 IDs, get job ID, comprehensive research results stored in S3 when complete

This endpoint accepts a batch of IDs and processes them asynchronously using specialized research agents and workflow orchestration, making it ideal for large-scale research operations.

Request Body

  • ids: Array of IDs to process for deep research (1-1000 IDs) (required)
  • query_hint: Query hint for research context (optional)
  • entity_type: Type of entity being processed (company or person) (required)
  • effort: Effort level for deep research processing (low, medium, high) - defaults to medium
  • agent_type: Type of specialized agent to use for deep research (defaults to 'general')
  • max_credits: Maximum credits this batch operation is allowed to consume (required)

Response

  • run_id: Unique identifier for the batch run
  • result_path: S3 bucket path where results will be stored upon completion
  • credits_csv_path: S3 bucket path where credit usage report will be stored upon completion

Processing

  1. IDs are converted to CSV format with entity type, agent type, and query hint enrichment
  2. CSV is uploaded to S3 storage
  3. Deep research workflow is triggered for batch processing
  4. Results are stored in the specified S3 location

Entity Types

Supported entity types for deep research:

  • company: Business organizations and companies
  • person: Individual contacts and people

Agent Types

Different agent types specialize in different research domains:

  • general: General purpose research agent (default)
  • funding: Research funding opportunities, investors, grants
  • legal: Legal research, compliance, regulatory information

Credit Usage

Credits are consumed based on the effort level, number of records processed, and research complexity. Higher effort levels consume more credits but provide more comprehensive results.

Batch Limits

  • Minimum: 1 ID
  • Maximum: 1000 IDs per batch
  • Invalid or empty IDs will be skipped

Example

{
  "ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "a1b2c3d4-e5f6-7890-abcd-ef1234567891", "a1b2c3d4-e5f6-7890-abcd-ef1234567892"],
  "query_hint": "Research funding opportunities for AI startups",
  "entity_type": "company",
  "effort": "medium",
  "agent_type": "funding",
  "max_credits": 200
}
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of strings, [ 1 .. 1000 ] items(Ids)required

List of IDs to process for deep research

query_hintstring(Query Hint)

Query hint for research context (optional)

Default:""
entity_typestring(EntityType)required

Type of entity being processed (company or person)

Enum:"person""company"
effortstring(EnrichmentEffortType)

Effort level for deep research processing

Default:"medium"
Enum:"low""medium""high"
agent_typestring(AgentType)

Type of specialized agent to use for deep research (defaults to 'general')

Default:"general"
Enum:"funding""legal""general"
max_creditsinteger, > 0(Max Credits)required

Maximum credits this request is allowed to consume

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/agents/deep-research \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "string"
    ],
    "query_hint": "",
    "entity_type": "person",
    "effort": "low",
    "agent_type": "funding",
    "max_credits": 0
  }'

Responses

Batch processing started successfully

Bodyapplication/json
run_idstring(Run Id)required

Unique identifier for the batch run

result_pathstring(Result Path)required

S3 bucket path where results will be stored

credits_csv_pathstring(Credits Csv Path)required

S3 bucket path where credit usage report will be stored

Response
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result_path": "s3://{s3_bucket}/{entity_type}/phone-email-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv",
  "credits_csv_path": "s3://{s3_bucket}/{entity_type}/phone-email-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv"
}