Batch analysis

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

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 [email protected].

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 below. webhook_url and metadata at the top level apply to items that don’t supply their own.

Response

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

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

Get started

Concepts

Guides

Reference

Request shape

Limits

Per-item fields

Top-level fields

Response

Delivery modes

`per_item` (default)

`batch`

Billing

Failures within a batch

When not to use batch

​Request shape

​Limits

​Per-item fields

​Top-level fields

​Response

​Delivery modes

​per_item (default)

​batch

​Billing

​Failures within a batch

​When not to use batch

Request shape

Limits

Per-item fields

Top-level fields

Response

Delivery modes

`per_item` (default)

`batch`

Billing

Failures within a batch

When not to use batch