> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Operations

> Run enrichment lookups at scale process hundreds or thousands of records in a single request.

## Overview

Encrata supports two bulk operation modes:

1. **Inline bulk** Send an array of queries in a single POST request (up to 100 items)
2. **Async bulk jobs** Upload a CSV file for background processing (up to 10,000 rows)

***

## Inline Bulk Endpoints

These endpoints accept an array of queries and return results synchronously. Best for smaller batches (≤100 items).

### Bulk Email Lookup

```bash theme={"dark"}
POST /api/bulk-lookup
```

<ParamField body="emails" type="string[]" required>
  Array of email addresses to enrich (max 1,000).
</ParamField>

**Example:**

```bash theme={"dark"}
curl -X POST "https://encrata.com/api/bulk-lookup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["alice@company.com", "bob@startup.io"] }'
```

Results are streamed via Server-Sent Events (SSE) for real-time progress.

***

### Bulk Google Search

```bash theme={"dark"}
POST /api/bulk-google-search
```

<ParamField body="queries" type="string[]" required>
  Array of search queries (max 100).
</ParamField>

***

### Bulk Company Search

```bash theme={"dark"}
POST /api/bulk-company-search
```

<ParamField body="queries" type="string[]" required>
  Array of company names or domains (max 100).
</ParamField>

***

### Bulk Domain Search

```bash theme={"dark"}
POST /api/bulk-domain-search
```

<ParamField body="queries" type="string[]" required>
  Array of domain names (max 100).
</ParamField>

***

### Bulk IP Search

```bash theme={"dark"}
POST /api/bulk-ip-search
```

<ParamField body="queries" type="string[]" required>
  Array of IP addresses (max 100).
</ParamField>

***

## Async Bulk Jobs

For large-scale operations (100–10,000 records), use async bulk jobs. Upload a CSV, and results are processed in the background.

### Create Bulk Job

```bash theme={"dark"}
POST /api/bulk-jobs
```

Upload a CSV file with a column of queries. The job processes in the background and notifies you when complete.

**Form fields:**

| Field    | Type   | Required | Description                                                         |
| -------- | ------ | -------- | ------------------------------------------------------------------- |
| `file`   | file   | Yes      | CSV file with queries                                               |
| `type`   | string | Yes      | Lookup type: `email`, `phone`, `company`, `domain`, `ip`, `darkweb` |
| `column` | string | No       | Column name containing the queries (auto-detected if omitted)       |

**Example:**

```bash theme={"dark"}
curl -X POST "https://encrata.com/api/bulk-jobs" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@leads.csv" \
  -F "type=email"
```

**Response:**

```json theme={"dark"}
{
  "id": "job_abc123",
  "status": "processing",
  "total_rows": 5000,
  "processed": 0,
  "created_at": "2026-06-01T10:00:00Z"
}
```

***

### Get Bulk Job Status

```bash theme={"dark"}
GET /api/bulk-jobs?id={job_id}
```

Returns current progress and status.

**Response:**

```json theme={"dark"}
{
  "id": "job_abc123",
  "status": "completed",
  "total_rows": 5000,
  "processed": 5000,
  "credits_used": 5000,
  "created_at": "2026-06-01T10:00:00Z",
  "completed_at": "2026-06-01T10:05:30Z"
}
```

**Statuses:** `queued`, `processing`, `completed`, `failed`, `cancelled`

***

### Download Results

```bash theme={"dark"}
GET /api/bulk-jobs/download?id={job_id}
```

Downloads the enriched results as a CSV file once the job is complete.

***

### Cancel Bulk Job

```bash theme={"dark"}
DELETE /api/bulk-jobs?id={job_id}
```

Cancels a running bulk job. Already-processed rows are kept.

***

## Credits

Each row in a bulk operation consumes credits at the standard rate for that lookup type. Failed lookups (invalid input) do not consume credits.

| Lookup Type   | Credits per Row |
| ------------- | --------------- |
| Email         | 1               |
| Phone         | 1               |
| Company       | 1               |
| Domain        | 1               |
| IP            | 1               |
| Dark Web      | 1               |
| Google Search | 1               |

***

## Webhooks

When a bulk job completes, the `bulk_job.completed` webhook event is fired if you have webhooks configured.