Skip to content

Lantern API docs (1.4.1)

Overview

The Lantern API provides two major processing modes to enhance your contact and business data:

🔄 Sync API - Real-time Processing (/v1/enrich/) Process individual records and get immediate responses. Perfect for:

  • Real-time user interfaces
  • Single record processing
  • Immediate validation workflows

Available Services:

  • Phone Enrichment: Find phone numbers for contacts
  • Email Enrichment: Discover professional email addresses
  • Company Enrichment: Get comprehensive firmographics and website-verified data
  • Person Enrichment: Enrich person records with contact and professional data
  • AI Enrichment: Generate insights, analysis, and structured data using advanced language models
  • Deep Research: Comprehensive research using advanced language models with real-time search capabilities

🎯 Match API - Object Matching (/v1/match/) Match Account/Contact/Lead objects with sophisticated matching logic. Perfect for:

  • CRM data deduplication
  • Lead-to-account matching
  • Contact matching and merging

Available Services:

  • Account Matching: Match company records with exact, fuzzy, and AI-assisted logic
  • Contact Matching: Match contact records with grouped boolean logic
  • Lead Matching: Match lead records with confidence scoring and explanations

🔗 Salesforce API - Lead Conversion (/v1/salesforce/) Convert Salesforce Leads to Contacts and Accounts with intelligent matching. Perfect for:

  • Automated lead conversion workflows
  • CRM data management
  • Lead-to-contact merging

Available Services:

  • Lead Conversion: Convert leads to contacts and accounts with duplicate prevention
  • Auto-Merge: Intelligent merging with configurable policies
  • Round-Robin Assignment: Automatic owner assignment from pools

🎯 Routing API - Round Robin Assignment (/v1/routing/) Assign Salesforce objects to users using intelligent round-robin logic. Perfect for:

  • Fair distribution of leads and opportunities
  • Automated user assignment
  • Pool-based routing management

Available Services:

  • Round Robin Assignment: Assign objects to users with sequence tracking
  • Pool Management: Organize users into assignment pools
  • Reset Rules: Support for resetting rotation with specific reasons

⚡ Triggers API - Instant Enrichment (/v1/triggers/) Trigger instant enrichment on Salesforce record creation/updates. Perfect for:

  • Real-time data enrichment
  • Automated workflow triggers
  • Near real-time processing

Available Services:

  • Salesforce Webhooks: Real-time trigger processing via Platform Events
  • Polling Fallback: SOQL-based polling every 2 minutes for comprehensive coverage
  • Instant Enrichment: Automatic enrichment workflows on record changes

📊 Logs API - Audit & Reporting (/v1/logs/) Comprehensive audit trails and reporting for all routing actions. Perfect for:

  • Compliance and audit requirements
  • Performance analysis and monitoring
  • User activity tracking

Available Services:

  • Route Log Export: Export logs with filtering and multiple formats (JSON/CSV)
  • Log Statistics: Statistical analysis of log data for reporting
  • Retention Management: Configurable retention policies and cleanup schedules

🚀 Async API - Batch Processing (/v1/agents/) Process multiple records (1-1000) asynchronously with results stored in S3. Perfect for:

  • Large-scale bulk processing
  • Background processing workflows
  • Cost breakdown results on s3 too

Available Services:

  • Phone Enrichment Batch: Bulk phone number enrichment
  • Email Enrichment Batch: Bulk email address enrichment
  • Deep Research Batch: Bulk AI-powered research with specialized agents

💳 Credits API - Credit Management (/v1/credits/) Monitor and manage your credit usage and availability. Perfect for:

  • Tracking credit consumption across time periods
  • Checking remaining credit balance

Available Services:

  • Credit Usage: Get detailed usage statistics for specific date ranges
  • Remaining Credits: Check current credit balance

🔄 Workflow Trigger API - External System Integration (/v1/workflows/) Trigger enrichment and routing workflows from external systems. Perfect for:

  • Eloqua, CDP, and Data Lake integrations
  • Marketing automation platform triggers
  • High-volume bursty event processing

Available Services:

  • Workflow Trigger: Generic interface for initiating workflows from any external system
  • Audit Logging: Complete request/response logging for compliance
  • Retry Logic: Automatic retries with exponential backoff

📝 Form Submit API - Direct Form Processing (/v1/forms/) Accept form submissions and immediately enrich and disposition data. Perfect for:

  • Marketing automation platform integrations
  • Website form processing
  • Real-time lead enrichment

Available Services:

  • Form Submission: Accept form data with validation
  • Immediate Enrichment: Sub-5 second processing with GDPR compliance
  • Flexible Output: Return enriched data or push to external systems

Processing Mode Comparison

FeatureSync APIMatch APISalesforce APIRouting APITriggers APILogs APIAsync APICredits APIWorkflow APIForm API
Records per request11-100111-1001-100001-1000N/A11
Response timeImmediateImmediateImmediateImmediateImmediateImmediateAsynchronousImmediateImmediateImmediate
Result deliveryDirect responseDirect responseDirect responseDirect responseDirect responseDirect responseS3 storageDirect responseDirect responseDirect response
Use caseReal-time processingObject matchingLead conversionUser assignmentInstant enrichmentAudit reportingBulk operationsCredit monitoringExternal system triggersForm processing
Rate limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsPer-minute limitsLower frequency limitsPer-minute limitsHigh burst supportHigh burst support

Base URL

https://api-gateway.agenthq.withlantern.com

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting & Credits

  • Sync API Rate Limit: 50 requests per minute per API key. Can be lifted on request.
  • Async API Rate Limit: 1 batch request per minute per API key. Can be lifted on request.
  • Credits API Rate Limit: 10 requests per minute per API key. Can be lifted on request.
  • Headers: Rate limit and credit information is returned in response headers:
    • X-RateLimit-Limit: The rate limit ceiling for your API key
    • X-Credits-Remaining: Credits remaining in your account

Error Codes:

  • 429 Too Many Requests: Rate limit exceeded
  • 402 Payment Required: Credit limit exceeded

Best Practices

General Guidelines

  1. API Key Security: Keep your API key secure and never expose it in client-side code
  2. Rate Limit Handling: Implement exponential backoff when receiving 429 responses
  3. Error Handling: Always check the success field before processing results
  4. Credit Management: Monitor your credit usage and remaining balance through response headers

Sync API Guidelines

  1. Use Unique Record IDs: Always provide unique record IDs to enable caching and prevent duplicate processing
  2. Set Credit Limits: Use max_credits parameter to control spending per request
  3. Cache Awareness: Check the cached field to understand if fresh data was retrieved
  4. Monitor Confidence Levels: Use confidence scores to determine data quality for your use case

Async API Guidelines

  1. Batch Sizing: Submit 100-1000 records per batch for optimal performance
  2. Result Monitoring: Get submission details from API call when batch is accepted, then poll results from S3 until completion
  3. Credit Planning: Set appropriate max_credits limits for large batches
  4. Error Handling: Handle batch-level errors and individual record failures within results

Credits API Guidelines

  1. Proactive Monitoring: Check remaining credits before large operations
  2. Usage Tracking: Use date range filtering to analyze spending patterns
  3. Budget Planning: Monitor usage trends to forecast credit needs

AI Enrichment

  1. Clear Queries: Be specific and provide context for better responses
  2. JSON Format: Enable JSON formatting for structured data extraction tasks
  3. Monitor Confidence: Pay attention to confidence scores for quality assessment
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Lantern API server

https://api-gateway.agenthq.withlantern.com/

Local API server

http://localhost:8000/

Enrichment

Operations

Match

Operations

Salesforce

Operations

Routing

Operations

Triggers

Operations

Logs

Operations

Batch Agents

Operations

Phone Enrichment Batch

Request

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

{
  "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:

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

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
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of Ids (strings) or Ids (null)(Ids)
Any of:

List of IDs to process for phone enrichment

[ 1 .. 1000 ] items
recordsArray of Records (objects) or Records (null)(Records)
Any of:

List of record objects to process for phone enrichment

[ 1 .. 1000 ] items
entity_typestring(Entity Type)

Type of entity being processed (must be 'person' for phone enrichment)

Default "person"
Value "person"
max_creditsinteger(Max Credits)> 0required

Maximum credits this request is allowed to consume

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/agents/phone \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "person",
    "ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "max_credits": 100
  }'

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
application/json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "result_path": "s3://{s3_bucket}/{entity_type}/phone-enrichment-batch_2025-01-15_550e8400-e29b-41d4-a716-446655440000.csv",
  "credits_csv_path": "s3://{s3_bucket}/{s3_prefix}/phone-enrichment/2025-01-15/550e8400-e29b-41d4-a716-446655440000_credits.csv"
}

Email Enrichment Batch

Request

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

{
  "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:

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

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
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of Ids (strings) or Ids (null)(Ids)
Any of:

List of IDs to process for email enrichment

[ 1 .. 1000 ] items
recordsArray of Records (objects) or Records (null)(Records)
Any of:

List of record objects to process for email enrichment

[ 1 .. 1000 ] items
entity_typestring(Entity Type)

Type of entity being processed (must be 'person' for email enrichment)

Default "person"
Value "person"
max_creditsinteger(Max Credits)> 0required

Maximum credits this request is allowed to consume

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/agents/email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "person",
    "ids": [
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "6ba7b812-9dad-11d1-80b4-00c04fd430c8"
    ],
    "max_credits": 100
  }'

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
application/json
{
  "run_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "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"
}

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(Ids)[ 1 .. 1000 ] itemsrequired

List of IDs to process for deep research

query_hintstring(Query Hint)

Query hint for research context (optional)

Default ""
entity_typestring(EntityType)required
Enum"person""company"
effortstring(EnrichmentEffortType)
Default "medium"
Enum"low""medium""high"
agent_typestring(AgentType)
Default "general"
Enum"funding""legal""general"
max_creditsinteger(Max Credits)> 0required

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

Phone & Email Enrichment Batch

Request

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

{
  "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:

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

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
Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of Ids (strings) or Ids (null)(Ids)
Any of:

List of IDs to process for phone enrichment

[ 1 .. 1000 ] items
recordsArray of Records (objects) or Records (null)(Records)
Any of:

List of record objects to process for phone enrichment

[ 1 .. 1000 ] items
entity_typestring(Entity Type)

Type of entity being processed (must be 'person' for phone enrichment)

Default "person"
Value "person"
max_creditsinteger(Max Credits)> 0required

Maximum credits this request is allowed to consume

curl -i -X POST \
  https://api-gateway.agenthq.withlantern.com/v1/agents/phone-email \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "person",
    "ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ],
    "max_credits": 100
  }'

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
application/json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "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"
}

Get Run Status

Request

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

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

CodeMeaning
200 OKRun status retrieved successfully
400 Bad RequestInvalid run ID format
404 Not FoundRun not found
500 Internal Server ErrorServer error occurred while retrieving status
Security
BearerAuth
Path
run_idstring(Run Id)required
curl -i -X GET \
  'https://api-gateway.agenthq.withlantern.com/v1/agents/runs/{run_id}/status' \
  -H 'Authorization: Bearer <YOUR_ApiToken_HERE>'

Responses

Run status retrieved successfully

Bodyapplication/json
run_idstring(uuid)(Run Id)required

Unique identifier for the run

Example: "123e4567-e89b-12d3-a456-426614174000"
statusstring(RunStatus)required
Enum"queued""queued""failed""completed""failed"
Example: "queued"
Response
application/json
{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed"
}

Credits

Operations

Forms

Operations

Workflows

Operations