# Batch Agents

## Phone Enrichment Batch

 - [POST /v1/agents/phone](https://developers.withlantern.com/openapi/batch-agents/phone_enrich_batch_v1_agents_phone_post.md): Process multiple records for phone enrichment in batch mode.

## Overview
The Phone Enrichment Batch API allows you to submit multiple person records for phone number enrichment processing asynchronously.

Key Differences from Sync API:
- Sync API (/v1/enrich/phone): Process one record at a time, get immediate response with phone number
- Batch API (/v1/agents/phone): Submit 1-1000 records, get job ID, results stored in S3 when complete

This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration, making it ideal for bulk processing operations.

## Request Body


Submit IDs for processing:
- ids: Array of person IDs to process (1-1000 IDs)



Required fields:
- entity_type: Type of entity being processed (must be 'person' for phone enrichment) (required)
- 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


## Credit Usage
Credits are consumed based on the number of records processed and the success rate of phone number lookups. The batch will stop processing if the credit limit is reached.

## Batch Limits
- Minimum: 1 record
- Maximum: 1000 records per batch
- Records with missing required fields will be skipped

## Examples

### Example: Submit IDs for processing
json
{
  "ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"],
  "entity_type": "person",
  "max_credits": 100
}




## Output

The results CSV will contain the following columns:

json
{
  "id": "string | Unique record identifier",
  "first_name": "string | Person's given name",
  "last_name": "string | Person's surname",
  "company_name": "string | Organization name",
  "company_url": "string | Company website domain",
  "linkedin": "string | LinkedIn profile URL or username",
  "phone_number": "string | Phone number (E.164 format when available)",
  "phone_found": "boolean | Phone enrichment success flag"
}


### Example Output CSV
csv
id,first_name,last_name,company_name,company_url,linkedin,phone_number,phone_found
550e8400-e29b-41d4-a716-446655440001,John,Smith,Acme Corp,acme.com,john-smith-123456789,+1-555-123-4567,true
550e8400-e29b-41d4-a716-446655440002,Jane,Doe,TechCorp,techcorp.com,jane-doe-987654321,,false

## Email Enrichment Batch

 - [POST /v1/agents/email](https://developers.withlantern.com/openapi/batch-agents/email_enrich_batch_v1_agents_email_post.md): Process multiple records for email enrichment in batch mode.

## Overview
The Email Enrichment Batch API allows you to submit multiple person records for email address enrichment processing asynchronously.

Key Differences from Sync API:
- Sync API (/v1/enrich/email): Process one record at a time, get immediate response with email address
- Batch API (/v1/agents/email): Submit 1-1000 records, results stored in S3 when complete

This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration, making it ideal for bulk processing operations.

## Request Body


Submit IDs for processing:
- ids: Array of person IDs to process (1-1000 IDs)



Required fields:
- entity_type: Type of entity being processed (must be 'person' for email enrichment) (required)
- 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


## Credit Usage
Credits are consumed based on the number of records processed and the success rate of email address lookups. The batch will stop processing if the credit limit is reached.

## Batch Limits
- Minimum: 1 record
- Maximum: 1000 records per batch
- Records with missing required fields will be skipped

## Examples

### Example: Submit IDs for processing
json
{
  "ids": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8", "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "6ba7b812-9dad-11d1-80b4-00c04fd430c8"],
  "entity_type": "person",
  "max_credits": 100
}




## Output

The results CSV will contain the following columns:

json
{
  "id": "string | Unique record identifier",
  "first_name": "string | Person's given name",
  "last_name": "string | Person's surname",
  "company_name": "string | Organization name",
  "company_url": "string | Company website domain",
  "linkedin": "string | LinkedIn profile URL or username",
  "email": "string | Email address",
  "email_found": "boolean | Email enrichment success flag"
}


### Example Output CSV
csv
id,first_name,last_name,company_name,company_url,linkedin,email,email_found
6ba7b810-9dad-11d1-80b4-00c04fd430c8,John,Smith,Acme Corp,acme.com,john-smith-123456789,john.smith@acme.com,true
6ba7b811-9dad-11d1-80b4-00c04fd430c8,Jane,Doe,TechCorp,techcorp.com,jane-doe-987654321,,false

## Deep Research Batch

 - [POST /v1/agents/deep-research](https://developers.withlantern.com/openapi/batch-agents/deep_research_batch_v1_agents_deep_research_post.md): 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

json
{
  "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
}

## Phone & Email Enrichment Batch

 - [POST /v1/agents/phone-email](https://developers.withlantern.com/openapi/batch-agents/phone_email_enrich_batch_v1_agents_phone_email_post.md): Process multiple records for combined phone and email enrichment in batch mode.

## Overview
The Phone & Email Enrichment Batch API allows you to submit multiple person records for both phone number and email address enrichment processing asynchronously in a single operation.

Key Differences from Individual APIs:
- Phone API (/v1/agents/phone): Process records for phone enrichment only
- Email API (/v1/agents/email): Process records for email enrichment only
- Phone & Email API (/v1/agents/phone-email): Process records for both phone and email enrichment simultaneously

This endpoint accepts a batch of records and processes them asynchronously using workflow orchestration for both phone and email enrichment, making it ideal for comprehensive contact enrichment operations.

## Request Body
Submit IDs for processing:
- ids: Array of person IDs to process (1-1000 IDs)

Required fields:
- entity_type: Type of entity being processed (must be 'person' for phone & email enrichment) (required)
- 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

## Credit Usage
Credits are consumed based on the number of records processed and the success rate of both phone and email lookups. The batch will stop processing if the credit limit is reached.

## Batch Limits
- Minimum: 1 record
- Maximum: 1000 records per batch
- Records with missing required fields will be skipped

## Example

### Example: Submit IDs for processing
json
{
  "ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003"],
  "entity_type": "person",
  "max_credits": 200
}


## Output

The results CSV will contain the following columns:

json
{
  "id": "string | Unique record identifier",
  "first_name": "string | Person's given name",
  "last_name": "string | Person's surname",
  "company_name": "string | Organization name",
  "company_url": "string | Company website domain",
  "linkedin": "string | LinkedIn profile URL or username",
  "email": "string | Email address",
  "email_found": "boolean | Email enrichment success flag",
  "phone_number": "string | Phone number (E.164 format when available)",
  "phone_found": "boolean | Phone enrichment success flag"
}


### Example Output CSV
csv
company_name,company_url,first_name,id,last_name,linkedin,email,email_found,phone_number,phone_found
Acme Corp,acme.com,John,550e8400-e29b-41d4-a716-446655440001,Smith,john-smith-123456789,john.smith@acme.com,true,+1-555-123-4567,true
TechCorp,techcorp.com,Jane,550e8400-e29b-41d4-a716-446655440002,Doe,jane-doe-987654321,,false,,false
Global Solutions,globalsolutions.com,Michael,550e8400-e29b-41d4-a716-446655440003,Johnson,michael-johnson-345678901,michael.johnson@globalsolutions.com,true,,false

## Get Run Status

 - [GET /v1/agents/runs/{run_id}/status](https://developers.withlantern.com/openapi/batch-agents/get_workflow_run_status_v1_agents_runs__run_id__status_get.md): Retrieve the current status of a run by its ID.

## Overview
This endpoint allows you to quickly check the status of a run without retrieving all the detailed information.

## Path Parameters
- run_id: The unique identifier of the batch run (UUID format)

## Response
Returns the run ID and its current status.

## Examples

### Example Response
json
{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed"
}


### Possible Status Values
- queued: The run is queued
- completed: The run has completed successfully
- failed: The run has failed

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 OK | Run status retrieved successfully |
| 400 Bad Request | Invalid run ID format |
| 404 Not Found | Run not found |
| 500 Internal Server Error | Server error occurred while retrieving status |