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

# Batch analysis

> Submit up to 50 properties in one call with `POST /v1/batch`.

If you need to analyze a list of parcels — a portfolio review, a search-results page, a comparison view — `POST /v1/batch` is more efficient than firing N parallel `POST /v1/analyze` calls. Each item is still its own report (priced and tracked individually), but you submit them as a single request and get a single batch ID back.

## Request shape

```bash theme={null}
curl -X POST https://api.acrelens.com/v1/batch \
  -H "Authorization: Bearer al_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "items": [
      { "address": "123 Cabin Rd, Taos, NM",   "state": "NM", "mode": "off_grid",          "acreage": 5.2 },
      { "address": "456 Ranch Ln, Bozeman, MT", "state": "MT", "mode": "rural_residential", "acreage": 12.0 },
      { "address": "789 Hilltop Dr, Asheville, NC", "state": "NC", "mode": "investment",   "acreage": 3.5 }
    ],
    "delivery_mode": "per_item",
    "webhook_url": "https://myapp.com/webhooks/acrelens",
    "metadata": { "source": "portfolio-import" }
  }'
```

## Limits

| | Value |
| - | - |
| Min items per batch | **2** |
| Max items per batch | **50** |
| Idempotency support | Yes — same key + same body returns the original `batch_id` |

If you need higher per-batch limits (volume contracts), email [support@acrelens.com](mailto:support@acrelens.com).

## Per-item fields

Each item accepts the same fields as `POST /v1/analyze`:

| Field | Type | Required | Notes |
| - | - | - | - |
| `address` | string | ✅ | 1–500 chars |
| `state` | string | ✅ | 2-letter US state code |
| `mode` | string | ✅ | `off_grid`, `rural_residential`, `recreational`, `investment` |
| `county` | string | | Improves regulation research |
| `acreage` | number | | Total acreage (positive) |
| `lat` | number | | Skips geocoding if provided |
| `lng` | number | | Skips geocoding if provided |
| `webhook_url` | string | | Per-item override of the batch-level webhook |
| `metadata` | object | | Up to 10 key-value pairs, returned in the report |

Each item can use a different `mode` — useful when comparing different perspectives on the same parcel.

## Top-level fields

| Field | Type | Required | Default |
| - | - | - | - |
| `items` | array | ✅ | — |
| `delivery_mode` | enum | | `"per_item"` |
| `webhook_url` | string | | — |
| `metadata` | object | | — |

`delivery_mode` controls how completion events arrive — see [delivery modes](#delivery-modes) below.

`webhook_url` and `metadata` at the top level apply to items that don't supply their own.

## Response

```json theme={null}
{
  "batch_id": "bat_01HY2Z...",
  "status": "processing",
  "items_count": 3,
  "reports": [
    {
      "report_id": "rpt_a...",
      "status": "processing",
      "poll_url": "https://api.acrelens.com/v1/reports/rpt_a..."
    },
    {
      "report_id": "rpt_b...",
      "status": "processing",
      "poll_url": "https://api.acrelens.com/v1/reports/rpt_b..."
    },
    {
      "report_id": "rpt_c...",
      "status": "processing",
      "poll_url": "https://api.acrelens.com/v1/reports/rpt_c..."
    }
  ],
  "delivery_mode": "per_item",
  "estimated_completion_seconds": 120
}
```

Status code: `202 Accepted`. Each `report_id` becomes a normal report you can `GET /v1/reports/{id}` like any other.

## Delivery modes

### `per_item` (default)

You receive a `report.completed` (or `report.failed`) webhook for **each** item as it finishes. Best for UIs that progressively render results.

### `batch`

You receive a single `batch.completed` webhook **after every item has finished** (success or failure). The payload includes all reports inline:

```json theme={null}
{
  "batch_id": "bat_01HY2Z...",
  "status": "completed",
  "items_count": 3,
  "completed_count": 2,
  "failed_count": 1,
  "items": [ /* full report bodies */ ]
}
```

Best for batch jobs that process the whole set atomically.

You can also combine: set `delivery_mode: "batch"` AND a per-item `webhook_url` if you want both.

## Billing

Each item is priced as an individual report (currently **\$3.99**). The full batch cost is deducted when the batch is created — not as each item finishes.

If your balance is insufficient to cover the entire batch, the API returns `402 insufficient_balance` and **no items are created**. Top up to at least `items_count × $3.99`, then retry with the same idempotency key.

Spend caps apply to the full batch cost, so a single batch can trip a daily or monthly cap that would have allowed individual reports.

## Failures within a batch

Some items completing while others fail is normal. Each item's status is independent — a `failed` report doesn't roll back the batch or refund the others. Check each report's `status` field after delivery.

## When not to use batch

* **Latency-sensitive single requests.** A single batch of 1 isn't allowed (min 2). Use `POST /v1/analyze` for one-offs.
* **Mixed priorities.** Items in a batch run roughly together. If one item is urgent, send it as its own request.
* **Different webhook secrets per item.** Webhook secrets are per-customer, not per-request — see [webhooks](/guides/webhooks#webhook-secret).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.