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

# Batch Processing

> Efficiently enrich multiple places with batch operations

## Overview

The Batch Processing API allows you to enrich hundreds or thousands of places in a single request. Instead of making individual API calls for each place, submit them all at once and retrieve results efficiently.

## Key Benefits

* **High Throughput** - Process thousands of places in parallel
* **Cost Efficient** - Reduced API overhead compared to individual requests
* **Progress Tracking** - Monitor batch status and completion
* **Automatic Retries** - Failed items are retried automatically
* **Result Management** - Download complete or partial results

## Quick Start

<Steps>
  <Step title="Create a Batch">
    Submit multiple places for enrichment in a single request:

    <CodeGroup>
      ```javascript Node.js theme={null}
      const response = await fetch(
        'https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches',
        {
          method: 'POST',
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            batch_name: 'Q1 2024 Store Locations',
            places: [
              {
                place_id: 'store_001',
                inputs: {
                  name: 'Downtown Store',
                  latitude: 40.7128,
                  longitude: -74.0060
                }
              },
              {
                place_id: 'store_002',
                inputs: {
                  name: 'Uptown Branch',
                  address: '789 Broadway, New York, NY'
                }
              },
              // ... up to 1000 places per batch
            ]
          })
        }
      );

      const batch = await response.json();
      console.log(`Batch created: ${batch.batch_id}`);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          'https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches',
          headers={
              'Authorization': 'Bearer YOUR_API_KEY',
              'Content-Type': 'application/json'
          },
          json={
              'batch_name': 'Q1 2024 Store Locations',
              'places': [
                  {
                      'place_id': 'store_001',
                      'inputs': {
                          'name': 'Downtown Store',
                          'latitude': 40.7128,
                          'longitude': -74.0060
                      }
                  },
                  {
                      'place_id': 'store_002',
                      'inputs': {
                          'name': 'Uptown Branch',
                          'address': '789 Broadway, New York, NY'
                      }
                  }
                  # ... up to 1000 places per batch
              ]
          }
      )

      batch = response.json()
      print(f"Batch created: {batch['batch_id']}")
      ```
    </CodeGroup>
  </Step>

  <Step title="Monitor Progress">
    Check the status of your batch:

    ```javascript theme={null}
    const statusResponse = await fetch(
      `https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches/${batch.batch_id}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const status = await statusResponse.json();
    console.log(`Progress: ${status.completed_count}/${status.total_count}`);
    console.log(`Status: ${status.status}`);
    ```
  </Step>

  <Step title="Retrieve Results">
    Once complete, download the enriched data:

    ```javascript theme={null}
    if (status.status === 'completed') {
      const results = status.results;
      
      results.forEach(place => {
        console.log(`${place.place_id}: ${place.enrichment_status}`);
        if (place.enriched_data) {
          console.log('  Enriched attributes:', place.enriched_data);
        }
      });
    }
    ```
  </Step>
</Steps>

## Batch Limits

* **Maximum places per batch**: 1,000
* **Maximum concurrent batches**: 10 per organization
* **Batch timeout**: 24 hours
* **Result retention**: 30 days

<Note>
  For larger datasets (>1,000 places), split them into multiple batches or contact support for enterprise options.
</Note>

## Batch Status Lifecycle

1. **queued** - Batch created and waiting to process
2. **processing** - Enrichment in progress
3. **completed** - All places processed successfully
4. **partial** - Some places failed, but batch is complete
5. **failed** - Batch processing failed entirely

## Monitoring Progress

### Polling for Updates

```javascript theme={null}
async function waitForBatchCompletion(batchId) {
  const pollInterval = 5000; // 5 seconds
  
  while (true) {
    const response = await fetch(
      `https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches/${batchId}`,
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    
    const status = await response.json();
    console.log(`Progress: ${status.completed_count}/${status.total_count}`);
    
    if (['completed', 'partial', 'failed'].includes(status.status)) {
      return status;
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}
```

### Progress Indicators

The batch status response includes:

```json theme={null}
{
  "batch_id": "batch_abc123",
  "batch_name": "Q1 2024 Store Locations",
  "status": "processing",
  "total_count": 500,
  "completed_count": 347,
  "failed_count": 3,
  "pending_count": 150,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:15:23Z",
  "estimated_completion": "2024-01-15T10:25:00Z"
}
```

## Handling Results

### Success Results

```javascript theme={null}
const successfulPlaces = status.results.filter(
  place => place.enrichment_status === 'completed'
);

successfulPlaces.forEach(place => {
  // Process enriched data
  const enrichedData = place.enriched_data;
  updateDatabase(place.place_id, enrichedData);
});
```

### Failed Items

```javascript theme={null}
const failedPlaces = status.results.filter(
  place => place.enrichment_status === 'failed'
);

failedPlaces.forEach(place => {
  console.error(`Failed to enrich ${place.place_id}:`, place.error_message);
  // Optionally retry or log for manual review
});
```

## Reprocessing Failed Items

Retry specific places from a batch:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches/${batchId}/reprocess`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        place_ids: ['store_001', 'store_015', 'store_042']
      })
    }
  );
  ```

  ```python Python theme={null}
  response = requests.post(
      f'https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{{org_slug}}/place_enrichment/batches/{batch_id}/reprocess',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'place_ids': ['store_001', 'store_015', 'store_042']
      }
  )
  ```
</CodeGroup>

## List All Batches

Retrieve all batches for your organization:

```javascript theme={null}
const response = await fetch(
  'https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const batches = await response.json();
batches.items.forEach(batch => {
  console.log(`${batch.batch_name}: ${batch.status} (${batch.completed_count}/${batch.total_count})`);
});
```

## Best Practices

<Tip>
  **Optimize Batch Size**: While you can submit up to 1,000 places per batch, smaller batches (100-300) complete faster and are easier to manage.
</Tip>

<Tip>
  **Use Descriptive Names**: Give your batches meaningful names to track different datasets or processing runs.
</Tip>

<Tip>
  **Handle Failures Gracefully**: Always check for failed items and implement retry logic for critical data.
</Tip>

<Tip>
  **Archive Results**: Download and store batch results locally - they're only retained for 30 days.
</Tip>

## Common Patterns

### CSV Upload Processing

```javascript theme={null}
import { parse } from 'csv-parse';
import fs from 'fs';

async function processCsvFile(filepath) {
  const places = [];
  
  // Parse CSV
  const parser = fs.createReadStream(filepath).pipe(parse({
    columns: true,
    skip_empty_lines: true
  }));
  
  for await (const row of parser) {
    places.push({
      place_id: row.id,
      inputs: {
        name: row.name,
        latitude: parseFloat(row.lat),
        longitude: parseFloat(row.lng),
        address: row.address
      }
    });
  }
  
  // Create batch
  const batch = await createBatch({
    batch_name: `CSV Import - ${filepath}`,
    places
  });
  
  return batch;
}
```

### Progressive Results Download

```javascript theme={null}
async function downloadResults(batchId) {
  let offset = 0;
  const limit = 100;
  const allResults = [];
  
  while (true) {
    const response = await fetch(
      `https://reprompt--reprompt-fastapi-fastapi-app.us-west.modal.run/{org_slug}/place_enrichment/batches/${batchId}?offset=${offset}&limit=${limit}`,
      {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    
    const data = await response.json();
    allResults.push(...data.results);
    
    if (data.results.length < limit) break;
    offset += limit;
  }
  
  return allResults;
}
```

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