Batch Processing

Endpoints

Action	Method & Path
Create batch	`POST /v1/{org_slug}/place_enrichment/batches`
Get batch status	`GET /v1/{org_slug}/place_enrichment/batches/{batch_id}`
Get batch results	`GET /v1/{org_slug}/place_enrichment/jobs?batchId={batch_id}&limit={n}&offset={n}`
Reprocess batch	`POST /v1/{org_slug}/place_enrichment/batches/{batch_id}/reprocess`
List batches	`GET /v1/{org_slug}/place_enrichment/batches?limit={n}&offset={n}`

Quick Start

Submit a minimal batch via the Create batch endpoint:

Request

{
  "batch_name": "Q1 Store Locations",
  "jobs": [
    {
      "place_id": "store_001",
      "inputs": {
        "name": "Downtown Store",
        "full_address": "123 Main St, New York, NY 10001",
        "latitude": 40.7128,
        "longitude": -74.0060
      }
    }
  ],
  "attributes": ["websites", "phoneNumbers", "categories"]
}

Include full_address in jobs[].inputs when available — it improves enrichment accuracy.

The same response shape is returned by Create batch and Get batch status. The jobs object lists place IDs grouped by their job status (see Monitoring Progress).

Response

{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 Store Locations",
  "status": "pending",
  "jobs": {
    "pending": ["store_001"],
    "queued": [],
    "in_progress": [],
    "completed": [],
    "failed": []
  }
}

Batch Limits

Maximum places per request: 50,000

Requests exceeding this limit return 400 Bad Request. Split larger datasets into multiple batches (for example, up to 50,000 places per batch).

Batches move through a small set of statuses driven by job state. The top-level status aggregates all jobs in the batch (e.g. in_progress if any job is still running). A batch is finished when status is completed or failed.

Not Started: Batch created; jobs are pending and not yet queued for processing.
Queued: Jobs are scheduled and waiting to be picked up by workers.
Processing: Jobs are actively being enriched by workers.
Completed: All jobs finished successfully.
Failed: Batch failed (e.g. too many job failures).

Monitoring Progress

Poll for batch status

Call GET /batches/{batch_id} on an interval (e.g. every 5–10 seconds).

Stop when terminal

Stop polling when top-level status is completed or failed.

Batch status response

The response exposes job-level status via the jobs object. Each key is a job status; each value is an array of place IDs whose enrichment job is in that status. Use the array lengths to derive progress (e.g. jobs.completed.length + jobs.failed.length over total).

Field	Description
`id`	Batch identifier
`batch_name`	Display name
`status`	Aggregated batch status (`pending`, `queued`, `in_progress`, `completed`, `failed`)
`jobs`	Place IDs grouped by job status: `pending`, `queued`, `in_progress`, `completed`, `failed`
`metadata`	Optional: `total_jobs`, `completed_jobs`, `status_counts`, `success_rate`
`created_at`	Batch creation timestamp

jobs is keyed by job status, not counts. Each array contains the place_id values for jobs in that status. Total jobs = sum of lengths across all job arrays.

{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 2024 Store Locations",
  "status": "in_progress",
  "jobs": {
    "pending": ["store_001", "store_002"],
    "queued": ["store_003", "store_004"],
    "in_progress": ["store_005"],
    "completed": ["store_006", "store_007"],
    "failed": []
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Handling Results

Fetch results

Request jobs for a batch

Use the Get batch results endpoint with batchId, limit, and offset. Returns { jobs, total, limit, offset }.

Paginate through all results

Increment offset by limit until offset + jobs.length >= total.

Success vs failed jobs

Each job in the jobs array has a status field. Filter by:

status === "completed" — successful enrichments; use outputs for enriched data
status === "failed" — failures; inspect for retry or manual review

Per-attribute run status (e.g. which enrichments ran or failed) lives under job_metadata.attribute_status. Use this for partial successes or to decide which attributes to reprocess.

Reprocessing Failed Items

POST /batches/{batch_id}/reprocess re-queues jobs for enrichment. Key options:

Param	Default	Description
`failed_only`	`true`	Only reprocess jobs with `failed` status
`incomplete_only`	`false`	Only reprocess pending/queued/in_progress
`refresh`	`false`	Force fresh enrichment, ignore cached data
`attributes`	—	Override attributes to enrich
`attribute_set`	—	Use predefined set: `core`, `all`, `open_closed`

Set failed_only: false and incomplete_only: false to reprocess all jobs in the batch.

Listing Batches

GET /batches?limit={n}&offset={n}&query={search} returns paginated batches. Each batch includes id, batch_name, status, status_counts, created_at, and optional metadata.

Best Practices

Descriptive batch names — Use names that identify the dataset or run so you can find them in the list.
Chunk large datasets — Stay under 50K jobs per request; split into multiple batches or append via repeated requests with the same batch_id.
Handle failures — Check jobs.failed after completion; use the reprocess endpoint to retry with failed_only: true.

Next Steps

Learn about Place Job Results for understanding enrichment output
Check the API Reference for complete endpoint documentation