Batch Operations

Overview

Use batch operations to process multiple requests in a single API call, reducing overhead and improving efficiency.

Batch Upload

Upload multiple documents at once:

curl -X POST https://api.solatis.team/v1/batch/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "name": "doc1.pdf",
        "url": "https://example.com/doc1.pdf",
        "metadata": {"source": "email"}
      },
      {
        "name": "doc2.pdf",
        "url": "https://example.com/doc2.pdf",
        "metadata": {"source": "website"}
      }
    ]
  }'

Response:

{
  "batch_id": "batch_123456",
  "status": "processing",
  "documents": [
    { "id": "doc1", "status": "queued" },
    { "id": "doc2", "status": "queued" }
  ],
  "progress": { "completed": 0, "total": 2 }
}

Batch Analysis

Analyze multiple documents:

curl -X POST https://api.solatis.team/v1/batch/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc1", "doc2", "doc3"],
    "analysis_type": "summary",
    "language": "en"
  }'

Response:

{
  "batch_id": "batch_789",
  "status": "processing",
  "analyses": [
    { "document_id": "doc1", "status": "in_progress" },
    { "document_id": "doc2", "status": "queued" },
    { "document_id": "doc3", "status": "queued" }
  ]
}

Check Batch Status

curl https://api.solatis.team/v1/batch/batch_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "batch_id": "batch_123456",
  "status": "completed",
  "created_at": "2024-02-02T10:00:00Z",
  "completed_at": "2024-02-02T10:05:00Z",
  "progress": {
    "completed": 2,
    "total": 2,
    "failed": 0
  },
  "documents": [
    {
      "id": "doc1",
      "status": "completed",
      "result": { "summary": "..." }
    },
    {
      "id": "doc2",
      "status": "completed",
      "result": { "summary": "..." }
    }
  ]
}

Batch Status Values

Status	Meaning
queued	Waiting to process
processing	Currently being processed
completed	Successfully completed
failed	Failed to process
cancelled	Manually cancelled

Batch Limits

Limit	Value
Max documents per batch	1,000
Max concurrent batches	10
Batch timeout	24 hours
Max size per document	100MB

Examples

Python: Upload Batch

import requests

def batch_upload(api_key, documents):
    headers = {"Authorization": f"Bearer {api_key}"}
    payload = {"documents": documents}

    response = requests.post(
        "https://api.solatis.team/v1/batch/documents",
        headers=headers,
        json=payload
    )

    return response.json()

# Usage
docs = [
    {"name": "doc1.pdf", "url": "https://..."},
    {"name": "doc2.pdf", "url": "https://..."}
]

batch = batch_upload(api_key, docs)
print(f"Batch ID: {batch['batch_id']}")

Python: Wait for Batch

import requests
import time

def wait_for_batch(api_key, batch_id, timeout=3600):
    headers = {"Authorization": f"Bearer {api_key}"}
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(
            f"https://api.solatis.team/v1/batch/{batch_id}",
            headers=headers
        ).json()

        print(f"Status: {response['status']}")
        print(f"Progress: {response['progress']}")

        if response['status'] in ['completed', 'failed']:
            return response

        time.sleep(5)

    raise TimeoutError("Batch processing timeout")

# Usage
result = wait_for_batch(api_key, batch_id)

JavaScript: Batch Operations

async function batchUpload(apiKey, documents) {
  const headers = { Authorization: `Bearer ${apiKey}` };

  const response = await fetch(
    "https://api.solatis.team/v1/batch/documents",
    {
      method: "POST",
      headers,
      body: JSON.stringify({ documents })
    }
  ).then(r => r.json());

  return response;
}

async function waitForBatch(apiKey, batchId) {
  const headers = { Authorization: `Bearer ${apiKey}` };

  while (true) {
    const response = await fetch(
      `https://api.solatis.team/v1/batch/${batchId}`,
      { headers }
    ).then(r => r.json());

    if (response.status === 'completed') {
      return response;
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

Best Practices

1. Optimize Batch Size

# Good: Use full batch size
batch_size = 1000

# Bad: Single document per batch
batch_size = 1

2. Handle Partial Failures

# Check for failed items
for doc in batch['documents']:
    if doc['status'] == 'failed':
        # Handle error
        print(f"Failed: {doc['error']}")

3. Implement Retry Logic

def batch_with_retry(api_key, documents, max_retries=3):
    for attempt in range(max_retries):
        try:
            return batch_upload(api_key, documents)
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

4. Monitor Progress

# Get batch status regularly
for i in range(100):
    batch = get_batch_status(api_key, batch_id)
    percent = (batch['progress']['completed'] /
              batch['progress']['total'] * 100)
    print(f"Progress: {percent:.0f}%")

    if batch['status'] == 'completed':
        break

    time.sleep(1)

Error Handling

Too Many Requests in Batch

{
  "error": "batch_size_exceeded",
  "message": "Maximum 1000 documents per batch",
  "max_size": 1000
}

Batch Not Found

{
  "error": "batch_not_found",
  "message": "Batch batch_123 does not exist",
  "batch_id": "batch_123"
}

Performance Tips

1. Use maximum batch size (1,000) for fewer API calls
2. Monitor batch progress without excessive polling
3. Implement exponential backoff for polling
4. Process results incrementally as items complete
5. Group similar operations in same batch

Limitations

• Batches process sequentially within organization
• Large batches may take longer
• Results expire after 7 days
• Failed items don't retry automatically

Reference

See REST API Reference for complete batch endpoint documentation.