Session Events API specification (S2S)

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

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.
Dismissal	dismissal	Raised when a customer dismisses an offer.
Conversion	conversion_signal	Raised when a conversion occurs.
Purchase	purchase	Raised when a purchase is completed.

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>"
}

Common error codes

HTTP status	Meaning
400	Malformed request body.
401	Missing or invalid Authorization header.
422	Request validation failed.
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.