EventsBatch_submit
const url = 'http://localhost:3000/api/events/batch';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"backfill":true,"events":[{"subjectId":"example","action":"example","email":"hello@example.com","phone":"example","properties":{"additionalProperty":"example"},"occurredAt":"2026-04-15T12:00:00Z","clientEventId":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/events/batch \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "backfill": true, "events": [ { "subjectId": "example", "action": "example", "email": "hello@example.com", "phone": "example", "properties": { "additionalProperty": "example" }, "occurredAt": "2026-04-15T12:00:00Z", "clientEventId": "example" } ] }'Record up to 1000 events; a failing item does not affect the others
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Request body for recording events one by one with per-item results
object
Load history: the events are only recorded, so segments see them but no Automation enrolls on them and no webhook endpoint receives them. Use it to bring the events of an earlier system into a new setup. Defaults to false.
Events to record, at most 1000
Event payload
object
Canonical subject identifier
Event action
Email address associated with the event
Phone number associated with the event
Event properties
object
Event occurrence timestamp
A client-chosen id that makes a retry safe. It is unique within the Workspace: sending an event again with the same id changes nothing, so a load that broke off halfway is resent whole. Generate it once per event (a UUID) and reuse it on every retry. An event without one is not deduplicated.
Example generated
{ "backfill": true, "events": [ { "subjectId": "example", "action": "example", "email": "hello@example.com", "phone": "example", "properties": { "additionalProperty": "example" }, "occurredAt": "2026-04-15T12:00:00Z", "clientEventId": "example" } ]}Responses
Section titled “Responses”The request has succeeded.
Per-item results of an events batch
object
One result per request item, in request order
Per-item result of an events batch, in request order
object
Zero-based position of the item in the request
Accepted when published; failed when the item was rejected
Why the item failed; absent when accepted
Example
{ "results": [ { "status": "accepted" } ]}RFC 7807 bad request response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 unauthorized response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 validation response
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}RFC 7807 too many requests response: a rate limit was exceeded (ADR 0025)
RFC 7807 Problem Details
object
Why the request was refused, when the client should act on it
A URI reference that identifies the problem type
A short, human-readable summary of the problem type
HTTP status code
A human-readable explanation specific to this occurrence
A URI reference that identifies the specific occurrence
Validation errors grouped by field
object
Form-level validation error
Field validation errors
object
Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait
Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)
object
The error that failed the request, or the panic value
The goroutine stack of a panic; absent for an error a handler returned
The request id the server log carries for this request
The HTTP method of the failed request
The path of the failed request
Example
{ "code": "second_factor_required"}Headers
Section titled “Headers”Seconds to wait before retrying
The request budget of the window that was exceeded
Requests left in the current window
Unix time at which the window resets