--- title: "Batch Events" method: POST path: "/batch" tags: ["OursPrivacy"] --- # Batch Events `POST /batch` Send multiple `/track`-shaped events in a single request. This endpoint is intended for replay, backfill, and asynchronous bulk delivery. The top-level token is authorized once for the full batch. Each batch row must include `distinctId`, and mixed validation or queue outcomes are reported per row. ## Request body - object - `token` string, required — The token for your Source. You can find this in the dashboard. - `events` object[], required — A list of `/track`-shaped events to validate and enqueue together. - `event` string, required — The name of the event you're tracking. This must be whitelisted in the Ours dashboard. - `userId` string, nullable — The Ours Visitor ID stored in local storage and cookies on your web properties. When present, this is used directly — no lookup by externalId or email is performed. If you have both a userId and an externalId, send both so the event is attached to the right visitor without any lookup overhead. - `externalId` string, nullable — Your system's unique identifier for this user. We search your account for an existing visitor with this externalId and attach the event to them (resolving to their Ours Visitor ID). If no match is found, a new visitor is created. When present, email lookup is skipped. If you also have the userId from cookies or local storage, send both — it removes the lookup round-trip. - `email` string, nullable — The email address of a user. Used as a fallback lookup when neither userId nor externalId is provided. We search your account for a visitor with this email and attach the event to them. If no match is found, a new visitor is created. - `time` number, nullable — The time at which the event occurred in milliseconds since UTC epoch. The time must be in the past and within the last 7 days. - `eventProperties` object, nullable — Any additional event properties you want to pass along. - `userProperties` object, nullable — Properties to set on the visitor. (optional) You can also update these properties via the identify endpoint. - `email` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `gender` string, nullable - `date_of_birth` string, nullable - `phone_number` string, nullable - `city` string, nullable - `state` string, nullable - `zip` string, nullable - `country` string, nullable - `external_id` string, nullable - `company_name` string, nullable - `job_title` string, nullable - `ip` string, nullable — The IP address of the user - `custom_properties` object, nullable - `consent` object, nullable - `ad_id` string, nullable - `adset_id` string, nullable - `campaign_id` string, nullable - `alart` string, nullable - `aleid` string, nullable - `axwrt` string, nullable - `fbc` string, nullable - `fbp` string, nullable - `fbclid` string, nullable - `gad_source` string, nullable - `gbraid` string, nullable - `gclid` string, nullable - `ndclid` string, nullable - `oppref` string, nullable - `dclid` string, nullable - `qclid` string, nullable - `msclkid` string, nullable - `ttclid` string, nullable - `twclid` string, nullable - `clickid` string, nullable - `sccid` string, nullable - `irclickid` string, nullable - `im_ref` string, nullable - `clid` string, nullable - `sid` string, nullable - `li_fat_id` string, nullable - `referrer` string, nullable - `referring_domain` string, nullable - `user_agent` string, nullable - `user_agent_full_list` string, nullable - `utm_campaign` string, nullable - `utm_content` string, nullable - `utm_medium` string, nullable - `utm_name` string, nullable - `utm_source` string, nullable - `utm_term` string, nullable - `wbraid` string, nullable - `rdt_cid` string, nullable - `is_bot` string, nullable - `epik` string, nullable - `sacid` string, nullable - `basis_cid` string, nullable - `ob_click_id` string, nullable - `beeswax_auction_id` string, nullable - `admitad_uid` string, nullable - `_ef_transaction_id` string, nullable - `viant_click_id` string, nullable - `viant_impression_id` string, nullable - `defaultProperties` object, nullable — These properties are used throughout the Ours app to pass known values onto destinations - `is_bot` string, nullable — Whether we have detected that the user is a bot. This is set automatically by the Ours server primarily for events tracked through the web SDK. - `ad_id` string, nullable — The ad id for detected in the session. This is set by the web sdk automatically. - `adset_id` string, nullable — The adset id for detected in the session. This is set by the web sdk automatically. - `campaign_id` string, nullable — The campaign id for detected in the session. This is set by the web sdk automatically. - `alart` string, nullable — The AppLovin alart query parameter. Ex: alart123 - `aleid` string, nullable — The AppLovin aleid query parameter. Ex: aleid123 - `axwrt` string, nullable — The AppLovin pixel cookie value (_axwrt). Web-only. - `encoding` string, nullable — The browsers encoding. Ex: UTF-8 - `browser_name` string, nullable — The name of the browser. Ex: Chrome - `browser_version` string, nullable — The version of the browser. Ex: 114.0 - `cpu_architecture` string, nullable — The architecture of the CPU. Ex: x64 - `device_type` string, nullable — The type of device the user is using. Ex: mobile - `device_model` string, nullable — The model of the device. Ex: iPhone 13 - `device_vendor` string, nullable — The vendor of the device. Ex: Apple - `engine_name` string, nullable — The name of the browser engine. Ex: Blink - `engine_version` string, nullable — The version of the browser engine. Ex: 114.0 - `os_name` string, nullable — The name of the operating system. Ex: Windows - `os_version` string, nullable — The version of the operating system. Ex: 10.0 - `browser_language` string, nullable — The language of the browser. Ex: en-US - `current_url` string, nullable — The full url (including query params) of the current page - `webview` boolean, nullable — Whether the user is in a webview. Ex: true - `iframe` boolean, nullable — Whether the user is in an iframe. Ex: true - `sessionCount` number, nullable — The number of sessions the user has had. Ex: 3 - `activeDuration` number, nullable — The active time in milliseconds that the user had this tab active - `duration` number, nullable — The time in milliseconds since the page was loaded // script was loaded - `epik` string, nullable — The Pinterest Click ID. Ex: epik456 - `sacid` string, nullable — The StackAdapt Tracking ID. Ex: sacid123 - `basis_cid` string, nullable — The Basis DSP Click ID. Ex: basis_cid123 - `ob_click_id` string, nullable — The Outbrain click ID, captured from the `ob_click_id` URL parameter (Outbrain `{{ob_click_id}}` macro) on the landing page. Ex: ob_click_abc123 - `beeswax_auction_id` string, nullable — The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123 - `admitad_uid` string, nullable — The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123 - `_ef_transaction_id` string, nullable — The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123 - `viant_click_id` string, nullable — The Viant (Adelphic) Click ID, captured from the `viant_click_id` URL parameter (Viant `${ADELPHIC_CLICKID}` macro). Sent as `xid` on Viant postbacks. Ex: viant_click_abc123 - `viant_impression_id` string, nullable — The Viant (Adelphic) Impression ID, captured from the `viant_impression_id` URL parameter (Viant `${ADELPHIC_IMPRESSIONID}` macro). Sent as `imp_id` on Viant postbacks for post-view attribution. Ex: viant_imp_abc123 - `fbc` string, nullable — Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 - `fbclid` string, nullable — Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 - `fbp` string, nullable — Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397 - `gad_source` string, nullable — The Google Ad Source. Ex: google - `gbraid` string, nullable — The Google Braid ID. Ex: gbraid123 - `gclid` string, nullable — The Google Click ID. Ex: gclid123 - `ndclid` string, nullable — The NextDoor Click ID. Ex: ndclid123 - `oppref` string, nullable — The OpenAI Ads privacy-preserving reference, captured from the `oppref` URL parameter on landing pages (the OpenAI Pixel also stores it in a `__oppref` cookie). Sent to OpenAI Ads on Conversions API events for attribution. Ex: oppref_abc - `dclid` string, nullable — The DoubleClick Click ID. Ex: dclid123 - `qclid` string, nullable — The Quora Click ID. Ex: qclid123 - `rdt_cid` string, nullable — The Reddit Click ID. Ex: rdt_cid123 - `host` string, nullable — The host of the current page. Ex: example.com - `ip` string, nullable — The IP address of the user. Ex: 127.0.0.1 - `msclkid` string, nullable — The Microsoft Click ID. Ex: msclkid123 - `li_fat_id` string, nullable — The LinkedIn Click ID. Ex: li_fat_id123 - `pathname` string, nullable — The pathname of the current page. Ex: /home - `referrer` string, nullable — The referrer URL of the current page - `referring_domain` string, nullable — The referring domain of the current page - `screen_height` number, nullable — The height of the screen. Ex: 1080 - `screen_width` number, nullable — The width of the screen. Ex: 1920 - `title` string, nullable — The title of the current page - `user_agent` string, nullable — The user agent of the browser - `utm_campaign` string, nullable — The UTM Campaign. The web SDK automatically captures this from the query params. - `utm_content` string, nullable — The UTM Content. The web SDK automatically captures this from the query params. - `utm_medium` string, nullable — The UTM Medium. The web SDK automatically captures this from the query params. - `utm_name` string, nullable — The UTM Name. The web SDK automatically captures this from the query params. - `ttclid` string, nullable — The TikTok Click ID. Ex: ttclid123 - `twclid` string, nullable — The Twitter Click ID. Ex: twclid123 - `clickid` string, nullable — The Click ID. Ex: clickid123 - `clid` string, nullable — The Generic Click ID. Ex: clid123 - `sccid` string, nullable — The SnapChat Click ID. Ex: sccid123 - `irclickid` string, nullable — The Impact Click ID. Ex: irclickid123 - `im_ref` string, nullable — The Impact Click ID reference. Ex: im_ref123 - `utm_source` string, nullable — The UTM Source. The web SDK automatically captures this from the query params. - `utm_term` string, nullable — The UTM Term. The web SDK automatically captures this from the query params. - `version` string, nullable — The SDK version (e.g., web SDK or ingest-sdk-* via Stainless headers) - `wbraid` string, nullable — The WBRAID Identifier. The web SDK automatically captures this from the query params. - `uafvl` string, nullable — User agent as a full list of strings. - `page_hash` number, nullable — A random set of numbers for the page load - `sid` string, nullable — The session ID as assigned automatically by the web SDK. This is required for session replay - `new_s` boolean, nullable — Deprecated - `fv` boolean, nullable — Deprecated - `sr` string, nullable - `received_at` string, nullable — The time the event was received by an Ours server in ISO format - `identityContext` object, nullable — End-user network context for server-side calls. Required for probabilistic identity resolution when the caller is a backend server rather than an end-user browser. - `ip` string, required — The end-user IP address (not the server IP). - `userAgent` string, required — The end-user User-Agent string (not the server UA). - `distinctId` string, required — A unique identifier for this event used for deduplication. Highly recommended — if omitted, Ours will generate one for you, but supplying your own gives you stronger idempotency guarantees (e.g. a Stripe payment intent ID or your internal order ID). ## Response `200` Every event in the batch was accepted onto the ingest queue. - object - `success` boolean, required - `accepted` integer, required - `failed` integer, required - `results` union[], required - union - object - `index` integer, required - `success` true, required - object - `index` integer, required - `success` false, required - `code` 'invalid_event' | 'queue_failed', required - `message` string, required ## Other responses - `207` — At least one row was accepted and at least one row failed validation or queue transport. Correct and resubmit `invalid_event` rows. Retry only `queue_failed` rows with the same `distinctId` values. - `400` — Invalid JSON, missing `token`, missing or empty `events`, token mismatch, invalid gzip body, or every row failed validation. - `401` — The top-level token is invalid or is not allowed for the public HTTP API. - `413` — The request exceeded the configured body, batch-count, or per-event size limit. - `415` — The request used an unsupported content type or content encoding. - `500` — A transient source lookup failed or every accepted row failed queue transport. Retry the failed rows with the same `distinctId` values. --- [API](https://skmtc.dev/oursprivacy/apis/ours.md) · [All operations](https://skmtc.dev/oursprivacy/apis/ours/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/oursprivacy/ours/revisions/dc169f9305c2/schema)