Skip to content
Arc XP

Content Recommendations Batch API

The Content Recommendations Batch API accepts up to 100 user-behavior events in a single POST /collector/v1/events/batch and durably commits them to the ingestion pipeline.

For the single-event variant (POST /collector/v1/events), the wire format is identical: only the request body shape differs.

Endpoint summary

FieldValue
Method + pathPOST /collector/v1/events/batch
Request bodyJSON array of event objects (see schema below)
Max batch size100 events per request
Empty arrayNo-op; returns 202
SemanticsAll-or-nothing. If any record fails to commit, the whole batch fails. Retry the entire batch with exponential backoff.
Success response202 Accepted with empty body
Validation error422 Unprocessable Entity with HTTPValidationError body

Event schema

Each array element is a single event envelope — the same shape accepted by POST /collector/v1/events. The authoritative field reference (types, required vs. optional, and the full event_type enum) lives in the Events endpoint of the API Developer Guide. The batch endpoint adds only the wire-format rules below — the array wrapper, the 100-event cap, and all-or-nothing commit semantics.

Request format

POST /collector/v1/events/batch HTTP/1.1
Host: https://{org}-config-prod.api.arc-cdn.net
Content-Type: application/json


[
  {
    "user_id": "abc-123",
    "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
    "event_type": "page_view",
    "timestamp": "2026-03-27T14:30:00+00:00",
    "session_id": "sess-a1b2c3"
  },
  {
    "user_id": "abc-123",
    "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
    "event_type": "deepest_scroll",
    "timestamp": "2026-03-27T14:32:00+00:00",
    "event_value": 0.75,
    "session_id": "sess-a1b2c3"
  }
]

A successful call returns 202 Accepted with an empty body. The 202 reflects the asynchronous nature of the pipeline: events are durably committed before the response returns, but they have not yet been processed end-to-end into the recommendation system.

Behavior and guarantees

Asynchronous accept. 202 means durably accepted, not fully processed. Schema errors surface as 422 at the API layer; semantic errors (e.g. unknown item_id) surface downstream via metrics and operational tooling.

The Content Recommendations Batch API returns 202 as soon as the request body has been validated and the batch has been durably committed to the ingestion pipeline.

Error handling

StatusWhenCaller action
202Batch was durably accepted.None.
422Body failed validation (bad enum, naive datetime, missing field).Inspect the error pointer, fix the envelope, do not retry as-is.
500Transient server-side failure committing the batch.Retry the whole batch with exponential backoff. Surface to monitoring.

Sizing guidance

  • Flush on volume and time. A common pattern: flush when the in-memory queue hits 50 events or 1 second has elapsed since the last flush, whichever comes first. This keeps real-time recommendations fresh during low-traffic periods.
  • Backfills should pace themselves. When replaying historical logs, throttle to your tenant’s provisioned ingest throughput.

Example — JavaScript client

const events = [
    {
        user_id: "abc-123",
        item_id: "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
        event_type: "page_view",
        timestamp: "2026-03-27T14:30:00+00:00",
        session_id: "sess-a1b2c3",
    },
    // ... up to 100 envelopes
];








const res = await fetch("https://{org}-config-prod.api.arc-cdn.net/collector/v1/events/batch", {
    method: "POST",
    headers: {
        "content-type": "application/json",
        // arc-organization is normally injected by the gateway; only set
        // it explicitly when calling the service from inside the VPC.
        "arc-organization": "tenant-abc",
    },
    body: JSON.stringify(events),
});


if (res.status === 202) {
    // Durably accepted. Done.
} else if (res.status === 422) {
    // Schema bug in the producer; do NOT retry as-is.
    console.error(await res.json());
} else if (res.status >= 500) {
    // Transient. Retry the whole batch with backoff.
}

When not to use this endpoint

  • Content / item catalog updates. Use POST /collector/v1/content; the Content Recommendations Batch API is for user-behavior interactions only.