Send multiple conversion events in a single batch request for improved performance and efficiency.

When to Use This Endpoint

• Bulk importing historical events from another system
• High-throughput event ingestion (multiple events per second)
• Migrating events during platform integration
• Backfilling events after setting up attributors
• Processing events collected offline

When NOT to Use This Endpoint

• Sending single events in real-time (use POST /v1/events instead)
• Events requiring immediate individual confirmation
• When you need granular per-event error handling

Important Constraints

• Rate Limit: 10 requests/minute (lower than single event endpoint)
• Maximum Batch Size: 100 events per request
• Processing: Events are processed atomically (all succeed or all fail)
• Deduplication: Events with duplicate dedup_id values are silently ignored
• Response: Returns total count of ingested events

Deduplication Behavior

If you send 100 events but 5 have dedup_id values that already exist:

• Response: ingested_events: 95
• No error is raised for duplicates
• Existing events remain unchanged

Common Errors

• 400 Bad Request:
  • Batch exceeds 100 events
  • Invalid event structure in one or more events
  • Missing required fields in any event
• 403 Forbidden: API key lacks SendTrackingEvent scope
• 429 Too Many Requests: Exceeded 10 requests/minute rate limit

Best Practices

• Use batch size of 50-100 events for optimal performance
• Implement exponential backoff for rate limit errors
• Generate unique dedup_id for each event to prevent duplicates
• Monitor ingested_events count to detect deduplication

Related Endpoints

• POST /v1/events - Send single event
• GET /v1/events/status - Check event creation status