> ## Documentation Index
> Fetch the complete documentation index at: https://syncupai-robbalian-cleanup-deprecated-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Processing

> Submit places for enrichment asynchronously via batch endpoints.

### 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:

<RequestExample>
  ```json Request theme={null}
  {
    "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"]
  }
  ```
</RequestExample>

<Tip>
  Include `full_address` in `jobs[].inputs` when available — it improves enrichment accuracy.
</Tip>

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](#monitoring-progress)).

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
    "batch_name": "Q1 Store Locations",
    "status": "pending",
    "jobs": {
      "pending": ["store_001"],
      "queued": [],
      "in_progress": [],
      "completed": [],
      "failed": []
    }
  }
  ```
</ResponseExample>

## Batch Limits

**Maximum places per request**: 50,000

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

## Batch Status Lifecycle

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`.

1. <Badge color="gray">Not Started</Badge>: Batch created; jobs are pending and not yet queued for processing.
2. <Badge color="gray">Queued</Badge>: Jobs are scheduled and waiting to be picked up by workers.
3. <Badge color="blue">Processing</Badge>: Jobs are actively being enriched by workers.
4. <Badge color="green">Completed</Badge>: All jobs finished successfully.
5. <Badge color="red">Failed</Badge>: Batch failed (e.g. too many job failures).

## Monitoring Progress

<Steps>
  <Step title="Poll for batch status">
    Call `GET /batches/{batch_id}` on an interval (e.g. every 5–10 seconds).
  </Step>

  <Step title="Stop when terminal">
    Stop polling when top-level `status` is `completed` or `failed`.
  </Step>
</Steps>

### 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                                                                       |

<Info>
  `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.
</Info>

```json theme={null}
{
  "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

<Steps>
  <Step title="Request jobs for a batch">
    Use the **Get batch results** endpoint with `batchId`, `limit`, and `offset`. Returns `{ jobs, total, limit, offset }`.
  </Step>

  <Step title="Paginate through all results">
    Increment `offset` by `limit` until `offset + jobs.length >= total`.
  </Step>
</Steps>

### 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

<Tip>
  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.
</Tip>

<AccordionGroup>
  <Accordion title="Attribute status values" icon="circle-info">
    | Value                  | Meaning                           |
    | ---------------------- | --------------------------------- |
    | `RUN`                  | Enrichment ran successfully       |
    | `NOT_RUN`              | Enrichment was not executed       |
    | `ERROR`                | Enrichment failed                 |
    | `RUN_CONDITION_FAILED` | Skipped (missing required inputs) |
  </Accordion>
</AccordionGroup>

## 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 batch 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 Enrichment](/guides/place-enrichment) for single-item enrichment
* Explore [Geofencing](/guides/geofencing) for location-based batch queries
* Check the [API Reference](/api-reference) for complete endpoint documentation