---
title: "Batch Track Events"
method: POST
path: "/v2/events/batch"
---

# Batch Track Events

`POST /v2/events/batch`

## Request

- Base URL: `https://pub-api.conversion.ai/api`
- URL: `https://pub-api.conversion.ai/api/v2/events/batch`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

Record up to 200 custom events in a single request. Each event is processed independently.

The response includes summary counts and a per-event error list for any failures. Partial failures do not cause the entire request to fail.

## Request body

- object
  - `events` object[], required: An array of event objects to track.
    - `userId` string: 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.
    - `email` string, email: The contact's email address. At least one of `userId` or `email` is required.
    - `event` string, required: The name of the custom event to track. This is a freeform string.
    - `eventId` string: 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, the existing event is left unchanged, and the response reports success with `duplicate: true` and the original event's `cnvEventId`. If omitted, a new event is always created.
    - `data` object: An optional map of custom data to attach to the event.
    - `timestamp` string, date-time: An optional ISO 8601 timestamp for when the event occurred. Defaults to the current time if omitted.
    - `createContact` boolean: When `true`, creates the contact for this event if no existing contact matches `userId` or `email`. Overrides a `false` top-level `createContacts`. Creating a contact requires an `email`.
  - `createContacts` boolean: When `true`, creates the contact for every event in the batch whose `userId` or `email` matches no existing contact. Creating a contact requires an `email`.

## Response `200`

Batch processed. Check `errors` for individual failures.

- object
  - `data` object
    - `processed` integer, required: Total number of events in the request.
    - `tracked` integer, required: Number of events successfully tracked, including idempotent duplicates of already-tracked events.
    - `failed` integer, required: Number of events that failed.
    - `results` object[], required: An array of result objects in the same order as the input `events` array.
      - `success` boolean, required: `true` if the event was successfully tracked (including idempotent duplicates).
      - `cnvEventId` string, uuid: The Conversion engagement ID. Present on success. For a duplicate, this is the ID of the originally recorded event.
      - `cnvContactId` string, uuid: The Conversion contact ID. Present on success, but omitted for duplicates.
      - `duplicate` boolean: `true` when an event with the same `eventId` was already tracked. The row is an idempotent no-op: the existing event is unchanged and no new event is created. Omitted when `false`.
      - `error` string: A machine-readable error code. Present on failure.
      - `message` string: A human-readable error description. Present on failure.

## Other responses

- `401`: Authentication failed.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/conversion/apis/conversion-api.md) - [All operations](https://skmtc.dev/conversion/apis/conversion-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conversion/apis/conversion-api/revisions/8422f815402a?raw)