> ## Documentation Index > Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt > Use this file to discover all available pages before exploring further. # Batch Track Events > Record up to 200 custom events in a single request. Each event is processed independently. This endpoint does **not** create contacts, each contact must already exist. The response includes summary counts and a per-event error list for any failures. Partial failures do not cause the entire request to fail. ## OpenAPI ````yaml /openapi.json post /v2/events/batch openapi: 3.1.0 info: title: Conversion API version: 2.0.0 description: >- The Conversion API lets you programmatically manage contacts, track custom events, and manage their associated data. servers: - url: https://pub-api.conversion.ai/api security: - apiKey: [] paths: /v2/events/batch: post: summary: Batch Track Events description: >- Record up to 200 custom events in a single request. Each event is processed independently. This endpoint does **not** create contacts, each contact must already exist. The response includes summary counts and a per-event error list for any failures. Partial failures do not cause the entire request to fail. operationId: batchTrackEvents requestBody: required: true content: application/json: schema: type: object required: - events properties: events: type: array minItems: 1 maxItems: 200 description: An array of event objects to track. items: type: object description: A single event to track. required: - event properties: userId: type: string description: >- An external user identifier for the contact. At least one of `userId` or `email` is required. If `userId` matches a contact, that contact is used. If not, falls back to `email`. If the email matches a contact that has a different `userId`, a `conflicting_identifier` error is returned. examples: - user_12345 email: type: string format: email description: >- The contact's email address. At least one of `userId` or `email` is required. examples: - jane@example.com event: type: string description: >- The name of the custom event to track. This is a freeform string. examples: - log_in eventId: type: string description: >- An optional client-generated identifier for the event. Use stable identifiers (like order IDs) to make retries idempotent: if an event with this ID already exists, the duplicate is ignored and the existing event is left unchanged. If omitted, a new event is always created. examples: - evt_abc123 data: type: object additionalProperties: {} description: An optional map of custom data to attach to the event. timestamp: type: string format: date-time description: >- An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted. examples: basic: summary: Basic batch track value: events: - email: jane@example.com event: log_in data: device: mobile location: US timestamp: '2026-03-31T14:30:00Z' - userId: user_12345 event: plan_upgraded data: plan: pro timestamp: '2026-03-31T14:30:00Z' responses: '200': description: Batch processed. Check `errors` for individual failures. content: application/json: schema: type: object properties: data: type: object required: - processed - tracked - failed - results properties: processed: type: integer description: Total number of events in the request. tracked: type: integer description: Number of events successfully tracked. failed: type: integer description: Number of events that failed. results: type: array description: >- An array of result objects in the same order as the input `events` array. items: type: object required: - success properties: success: type: boolean description: '`true` if the event was successfully tracked.' cnvEventId: type: string format: uuid description: >- The Conversion engagement ID. Present on success. cnvContactId: type: string format: uuid description: The Conversion contact ID. Present on success. error: type: string description: >- A machine-readable error code. Present on failure. message: type: string description: >- A human-readable error description. Present on failure. examples: all-success: summary: All events tracked value: data: processed: 2 tracked: 2 failed: 0 results: - success: true cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901 cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 - success: true cnvEventId: c3d4e5f6-a7b8-9012-cdef-123456789012 cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 partial-failure: summary: Partial failure value: data: processed: 3 tracked: 1 failed: 2 results: - success: false error: invalid_email message: 'invalid email format: not-an-email' - success: true cnvEventId: b2c3d4e5-f6a7-8901-bcde-f12345678901 cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 - success: false error: contact_not_found message: contact not found '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: Missing or invalid API key value: error: code: unauthorized message: API key is required '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal: summary: Internal error value: error: code: internal_error message: failed to track events components: schemas: Error: type: object properties: error: type: object required: - code - message properties: code: type: string description: A machine-readable error code. examples: - invalid_email message: type: string description: A human-readable error description. examples: - 'invalid email format: not-an-email' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: >- Your Conversion API key. Found in **Settings > Integrations** in the dashboard. Format: `sk_live__`. ````