---
title: "Async portfolio property-report batch (3-50 addresses)"
method: POST
path: "/api/locus-place-report-batch"
tags: ["data", "search", "real-estate", "property", "property-research", "due-diligence", "public-records", "x402", "batch", "portfolio", "async", "property-records", "parcel-research", "address", "citations", "category:reports"]
---

# Async portfolio property-report batch (3-50 addresses)

`POST /api/locus-place-report-batch`

## Request

- Base URL: `https://api.locus.report`
- URL: `https://api.locus.report/api/locus-place-report-batch`
- Auth: API key in header `PAYMENT-SIGNATURE`

Async portfolio property-report job for 3 to 50 addresses. Preflights items, charges one batch price only if one is supported, and returns a pollable job with per-item report ids. Unsupported items get free diagnostics, with no hidden per-item charges. No valuation or screening. npx @velinussage/locus-agent-skill add.

## Request body

- object: One async settled job for 3-50 US addresses. Each item is preflighted before payment; unsupported items stay charge-free diagnostics.
  - `addresses` string[], required: US street addresses or ZIP/place strings to preflight and process as one settled async job. Intended for portfolio batches; min 3, max 50.
  - `radiusMeters` number
  - `lookbackDays` integer
  - `webhookUrl` string, uri

## Response `200`

Free pre-charge diagnostic when no batch items are chargeable.

- union: A `kind`-discriminated union: `place_report_batch_job` for a settled async job, or `place_report_batch_diagnostic` when no item is chargeable.
  - object
    - `kind` 'place_report_batch_job', required
    - `jobId` string, required
    - `status` 'payment_pending' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'failed', required
    - `statusUrl` string, uri, required
    - `pollAfterSeconds` integer, required
    - `counts` object, required
      - `total` integer, required
      - `chargeable` integer, required
      - `unsupported` integer, required
      - `queued` integer, required
      - `completed` integer
      - `failed` integer
    - `items` object[]
      - `idx` integer, required
      - `address` string, required
      - `status` 'payment_pending' | 'unsupported' | 'queued' | 'processing' | 'completed' | 'failed', required
      - `reportId` string
      - `reportUrl` string, uri
      - `errorCode` string
      - `diagnostic` unknown
    - `caveats` string[], required
  - object
    - `kind` 'place_report_batch_diagnostic', required
    - `charged` false, required
    - `status` 'no_chargeable_items', required
    - `counts` object, required
      - `total` integer, required
      - `chargeable` integer, required
      - `unsupported` integer, required
      - `queued` integer, required
      - `completed` integer
      - `failed` integer
    - `items` object[], required
      - `idx` integer, required
      - `address` string, required
      - `status` 'payment_pending' | 'unsupported' | 'queued' | 'processing' | 'completed' | 'failed', required
      - `reportId` string
      - `reportUrl` string, uri
      - `errorCode` string
      - `diagnostic` unknown
    - `message` string, required
    - `caveats` string[], required

## Other responses

- `202`: Successful paid artifact, or a free pre-charge diagnostic when the request is outside current coverage. Supported 3-50 address batch requests return 202 with a pollable jobId/statusUrl after one settlement; all-unsupported batches return a free 200 diagnostic.
- `400`: Invalid request body.
- `402`: Payment Required. For x402 v2, repeat the identical request with a valid PAYMENT-SIGNATURE header (legacy X-PAYMENT is accepted for compatibility). MPP is disabled for this lifecycle-bound tool.

---

[API](https://skmtc.dev/locus/apis/locus-api.md) · [All operations](https://skmtc.dev/locus/apis/locus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locus/apis/locus-api/revisions/ba7786b74adb?raw)