Batch Ingestion

Send multiple events in a single API call — up to 500 events per request for high-volume scenarios.

When to Use Batch

Use batch endpoints when:

• Settling multiple bets after a game concludes (e.g., 100 bets on a football match)
• Importing historical data from a legacy system
• Catch-up ingestion after downtime or network issues
• High-frequency scenarios where individual calls would exceed rate limits

Batch endpoints accept up to 500 events per request. For more than 500 events, split them into multiple batch calls.

Batch Endpoints

Each domain has a batch variant:

Domain	Batch Endpoint
Users	POST /api/v1/user/batch
Transactions	POST /api/v1/transaction/batch
Casino	POST /api/v1/casino/batch
Sports	POST /api/v1/sport/batch
Generic	POST /v1/events/batch

Batch Request Format

All batch endpoints use the same envelope:

{
  "events": [
    { /* event 1 */ },
    { /* event 2 */ },
    { /* ... up to 500 */ }
  ]
}

Each event in the array has the same schema as the single-event endpoint.

Example — Batch Sport Updates

Sending one open and two results (win and lose):

curl -X POST https://events.atlas.io/api/v1/sport/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "open",
        "user_id": "user_001",
        "currency": "BRL",
        "bet_id": "bet_001",
        "bet_dt": "2026-03-11T14:30:00Z",
        "ticket_status": "open",
        "bet_type": "SINGLE",
        "bet_timing": "PREMATCH",
        "bet_platform": "MOBILE",
        "bet_virtual": false,
        "bet_amount": 50.00,
        "bet_odds": 2.90,
        "selections": [{ "selection_id": "sel_001", "selection_status": "open" }]
      },
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "lose",
        "user_id": "user_002",
        "currency": "BRL",
        "bet_id": "bet_002",
        "bet_dt": "2026-03-11T16:00:00Z",
        "ticket_status": "lose",
        "bet_amount": 30.00,
        "win_amount": 0.00
      },
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "win",
        "user_id": "user_003",
        "currency": "BRL",
        "bet_id": "bet_003",
        "bet_dt": "2026-03-11T16:00:00Z",
        "ticket_status": "win",
        "bet_amount": 20.00,
        "win_amount": 58.00
      }
    ]
  }'

Batch Response

Full Success — 202 Accepted

All events were accepted and published to Kafka:

{
  "data": {
    "accepted": 3,
    "failed": 0,
    "events": [
      { "eid": "evt_001", "status": "accepted" },
      { "eid": "evt_002", "status": "accepted" },
      { "eid": "evt_003", "status": "accepted" }
    ]
  }
}

Partial Failure — 207 Multi-Status

Some events failed (e.g., Kafka publish error for specific events):

{
  "data": {
    "accepted": 2,
    "failed": 1,
    "events": [
      { "eid": "evt_001", "status": "accepted" },
      { "eid": "evt_002", "status": "accepted" },
      { "eid": null,      "status": "failed", "error": "kafka: publish timeout" }
    ]
  }
}

Validation Failure — 422 Unprocessable Entity

The entire batch is rejected if any event fails struct validation:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "events[2].bet_amount: required field missing"
  }
}

A 422 error means no events were processed. Fix the validation error and resubmit the entire batch. This is different from a 207 where partial events succeed.

Error Handling Pattern

async function sendBatchWithRetry(events, apiKey, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://events.atlas.io/api/v1/sport/batch', {
      method: 'POST',
      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ events }),
    });

    if (response.status === 202) {
      return await response.json(); // Full success
    }

    if (response.status === 207) {
      const result = await response.json();
      // Retry only the failed events
      const failedIndices = result.data.events
        .map((e, i) => e.status === 'failed' ? i : null)
        .filter(i => i !== null);
      events = failedIndices.map(i => events[i]);
      continue;
    }

    if (response.status === 422) {
      throw new Error('Validation error — fix payload before retrying');
    }

    if (response.status === 429) {
      // Exponential backoff for rate limits
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
      continue;
    }
  }
  throw new Error(`Failed after ${maxRetries} attempts`);
}

Performance Tips

Optimal batch size: 100–200 events per call balances throughput and failure isolation. Larger batches (up to 500) increase efficiency but mean more events to retry on partial failure.

Scenario	Recommendation
Real-time settlement	Single events (/api/v1/sport)
Bulk settlement (< 500 bets)	One batch call
Bulk settlement (> 500 bets)	Split into 500-event chunks, process in parallel
Historical import	Batch with event timestamps set in payload (registered_at, transaction_dt, bet_dt)

Deduplication

Atlas deduplicates events using the bet_id / round_id / transaction_id fields within each domain. Sending the same event twice will result in only one being processed.

Deduplication is eventual (within a few seconds). In high-throughput scenarios, avoid sending the same event in rapid succession as the dedup window may not have closed.