Session Events API specification (S2S)

This document outlines the endpoint necessary to submit Events to Rokt using the Session API (v2).

For the same contract as an interactive, schema-level reference, see the Session API reference.

Work with your Rokt account team to obtain the necessary credentials. For an end-to-end integration walkthrough, see Session API integration (S2S).

Endpoint

Environment	Action	URL
Production	POST	https://api.rokt.com/v2/sessions/events

note

There is no separate sandbox URL. To validate before going live, send the rokt-test-session: true header on the same endpoint. Test sessions are tagged and filtered out of production metrics. The header marks reporting only — it does not force an offer to serve. Remove the header to go live.

Request

Authorization headers

Header	Description	Type	Note
Authorization	Basic auth credentials	string	Basic base64(rpub:rsec) — the same public/secret API key pair used for the Offers call.
rokt-account-id	Your Rokt account ID	string	Required on every call.

Required headers

Header	Description	Type	Example
Content-Type	Media type	string	application/json

Root/Body

Property	Required	Type	Description
channel	Yes	object	Must contain "type": "s2s".
single_session	Yes	boolean	Set to true. Links every event in the request to the session identified by each event's session_id.
events	Yes	Event[]	Collection of events to send to Rokt.

Event

Property	Required	Type	Description
event_type	Yes	string	The kind of event. See Event types.
instance_id	Yes	string (UUID)	Client-generated UUID identifying this event, used for deduplication.
session_id	Yes	string	The top-level session_id returned by the offers call.
timestamp	Yes	number	Unix epoch milliseconds at which the event occurred.
data	Yes	object	See Event data.

Event data

Property	Required	Type	Description
parent_id	Yes	string	The instance_guid of the element this event is about, taken from the offers response (e.g. the creative's instance_guid for an impression; a response option's instance_guid for a response). Builds the session tree. Echo the value from the offers response verbatim — it may carry a type prefix (e.g. ad:<uuid>); send it exactly as returned.
page_instance_guid	Yes	string	The page_instance_guid from the offers response.
token	Yes	string	The event token for that element from the offers response.
capture_method	No	string	How the event was captured (e.g. ClientProvided).

note

Authenticate with the same Basic rpub:rsec credentials as the offers call, and identify the session with single_session: true plus a per-event session_id (the top-level session_id from the offers response).

Event types

Event	event_type	Description
Impression	impression	Raised when a placement, slot, or creative is rendered and visible to the customer. If there is an appearance delay, this occurs upon unhiding the view. Required for each element that renders.
Viewed	viewed	Raised when a placement is ≥50% visible in the viewport for at least one continuous second. Matches the IAB viewability definition and should exclude bot/invalid traffic. Required for each creative that becomes viewable.
Response	signal_response	Raised when a customer engages with a response option. Required for each response option interaction.

Request example

POST https://api.rokt.com/v2/sessions/events
Authorization: Basic base64(rpub:rsec)
rokt-account-id: <your Rokt account ID>
Content-Type: application/json

{
  "channel": { "type": "s2s" },
  "single_session": true,
  "events": [
    {
      "event_type": "impression",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ab",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234567000,
      "data": {
        "parent_id": "018f2a1b-3333-7abc-8def-creative001",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>",
        "capture_method": "ClientProvided"
      }
    },
    {
      "event_type": "viewed",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ac",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234568000,
      "data": {
        "parent_id": "018f2a1b-3333-7abc-8def-creative001",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>"
      }
    },
    {
      "event_type": "signal_response",
      "instance_id": "018f1234-5678-7abc-8def-0123456789ad",
      "session_id": "018f2a1b-2222-7abc-8def-session00001",
      "timestamp": 1751234572000,
      "data": {
        "parent_id": "018f2a1b-4444-7abc-8def-responseoption01",
        "page_instance_guid": "018f2a1b-0000-7abc-8def-page00000001",
        "token": "<event-token>"
      }
    }
  ]
}

Response

Success response (202 Accepted)

A successful call returns 202 Accepted with a refreshed session token to use on subsequent calls, plus per-event results.

Property	Type	Description
session_token	object	Refreshed session token (session_token.token) for the next call.
event_ids	string[]	IDs assigned to the accepted events, in request order.
errors	object[]	Per-event errors, each containing index, code, and message. Empty when every event is accepted.
warnings	object[]	Per-event warnings, same index/code/message shape. Empty when there are none.

When every event is accepted, errors and warnings are empty and event_ids has one entry per submitted event:

{
  "session_token": {
    "token": "<session_token>"
  },
  "event_ids": [
    "018f9c40-1a2b-7abc-8def-eventimpression",
    "018f9c40-1a2b-7abc-8def-eventviewed0001",
    "018f9c40-1a2b-7abc-8def-eventresponse01"
  ],
  "errors": [],
  "warnings": []
}

On a partial failure the call still returns 202; the accepted events appear in event_ids and each rejected event is reported in errors by its index in the request array:

{
  "session_token": {
    "token": "<session_token>"
  },
  "event_ids": [
    "018f9c40-1a2b-7abc-8def-eventimpression",
    "018f9c40-1a2b-7abc-8def-eventviewed0001"
  ],
  "errors": [
    {
      "index": 2,
      "code": "invalid_token",
      "message": "token does not match the element identified by parent_id"
    }
  ],
  "warnings": []
}

Error responses (4xx / 5xx)

Errors return a semantic HTTP status with a structured body:

{
  "error": "<code>",
  "message": "<detail>"
}

Validation failures carry error: "validation_failed" and an additional details[] array naming each offending field.

Common error codes

HTTP status	Meaning
400	Malformed request body, or a body that failed validation (error: "validation_failed").
401	Missing or invalid Authorization header.
429	Rate limited. Do not retry automatically — pause and contact your Rokt representative if 429s persist.
5xx	Unexpected server error. Retry after a brief delay (1–2 seconds). If the problem persists, contact support@rokt.com.