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

Field	Value
Method + path	`POST /collector/v1/events/batch`
Request body	JSON array of `event` objects (see schema below)
Max batch size	100 events per request
Empty array	No-op; returns `202`
Semantics	All-or-nothing. If any record fails to commit, the whole batch fails. Retry the entire batch with exponential backoff.
Success response	`202 Accepted` with empty body
Validation error	`422 Unprocessable Entity` with `HTTPValidationError` body
Auth error	`401 Unauthorized` if the `arc-organization` header is missing or unknown

Event schema

Field	Required	Notes
`user_id`	yes	Identifier of the user who triggered the event.
`item_id`	yes	Item the user interacted with.
`event_type`	yes	One of: `page_view`, `click`, `video_start`, `video_complete`, `video_progress`, `search`, `share`
`timestamp`	yes	ISO-8601 with explicit offset (e.g. `2026-03-27T14:30:00+00:00`). Naive datetimes → `422`
`event_value`	no	Numeric value; conventionally a fraction in `[0, 1]` for `video_progress`

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": "video_progress",
    "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

Status	When	Caller action
`202`	Batch was durably accepted.	None.
`401`	`arc-organization` missing or references an unknown tenant.	Check gateway config; the tenant must be provisioned in Content Recommendations API before sending.
`422`	Body failed validation (bad enum, naive datetime, missing field).	Inspect the error pointer, fix the envelope, do not retry as-is.
`500`	Transient 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.

Single-event intake: POST /collector/v1/events
Content / item catalog intake: POST /collector/v1/content