Create a batch job

post

https://api.extole.io/v6/batches

Creates a new asynchronous batch job that reads its data source row-by-row and dispatches a consumer event for each row. The data source can be a previously run report, an audience list, or an uploaded file asset (CSV, PSV, or JSON). The job begins processing immediately after creation; poll GET /v6/batches/{batchId} to monitor status. For small inline batches of events, use POST /v6/async-events in the event-api instead.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Batch job creation request.

Body of a POST /v6/batches request.

columns

array of objects

Column validation rules applied before the job begins dispatching. Each entry declares a column name and optional constraints; rows that fail validation are counted in failed_rows.

columns

data_source

required

Data source for the batch job. Required. Specify one of: REPORT (a previously completed report), AUDIENCE_LIST (an audience list build), or FILE_ASSET (an uploaded file asset).

default_event_name

string

Fallback event name used when a row does not supply its own event name. Applied when event_name is omitted and no event_name column is present in the row.

event_columns

array of strings

Column names in the data source whose values are used as event column values when dispatching each row. For example, ["person_id"] will pass the row's person_id value as the identity key for event dispatch.

event_columns

event_data

object

Static key-value pairs merged into every dispatched event's data map. These are applied in addition to any per-row data derived from event_columns.

event_name

string

Event name to dispatch for each row in the data source. When set, all rows dispatch this event regardless of any event_name column in the data. Omit to use the default_event_name or the per-row value from event_columns.

name

string

Human-readable label for the batch job. Used for display and filtering. Omit to leave unnamed.

scopes

array of strings

Access-control scopes that restrict which user roles can interact with this job. Accepted values: CLIENT_SUPERUSER, CLIENT_ADMIN.

400Validation error. Check the code field — common causes: missing or invalid data_source, unsupported event_name format, or a column reference that doesn't exist in the data source.

401Missing or invalid access token.

402Payment Required

403Forbidden

415Unsupported Media Type

429Too Many Requests