Skip to main content

​
CPX Exposure Event Schema

​
Overview

Event fired when the ad is actually exposed to the user.

​
Required Fields

FieldTypeDescription
event_typestringExposure event type (always cpx_exposure)
serve_tokenstringServe token provided in auction-result. Used to link exposure → click → conversion
session_idstringSession identifier passed from platform_request
platform_idstringID of the platform generating the event
brand_agent_idstringWinning brand agent from the auction-result
wallet_idstringWallet that will be charged for this exposure
pricingobjectPricing information for this exposure
timestampstringTimestamp when the exposure was detected (ISO 8601 format)

​
Pricing Object

FieldTypeDescription
unitstringBilling unit for this event (always CPX)
amount_centsintegerCharge amount in CENTS. (bid = pay). Minimum: 0

​
Optional Fields

FieldTypeDescription
exposure_metadataobjectOptional additional rendering context
extobjectExtension namespace for vendor-specific fields

​
Exposure Metadata Object

FieldTypeDescription
context_channelstringWhere the ad was displayed. Enum: ai_chat, voice_assistant, agentic
positionintegerPosition in the LLM or assistant output (if relevant). Minimum: 1
visibility_msintegerHow long the ad was visible (if measurable). Minimum: 0

​
Example

{
  "event_type": "cpx_exposure",
  "serve_token": "stk_abcxyz123",
  "session_id": "sess_001",
  "platform_id": "pf_openai_chat",
  "brand_agent_id": "ba_451",
  "wallet_id": "w_0021",
  "pricing": {
    "unit": "CPX",
    "amount_cents": 5
  },
  "exposure_metadata": {
    "context_channel": "ai_chat",
    "position": 1,
    "visibility_ms": 1200
  },
  "timestamp": "2025-11-14T18:00:00Z"
}

​
Validation Rules

  • event_type must be exactly cpx_exposure
  • pricing.unit must be exactly CPX
  • pricing.amount_cents must be an integer with minimum value of 0
  • timestamp must be in ISO 8601 date-time format
  • exposure_metadata.context_channel must be one of: ai_chat, voice_assistant, agentic
  • exposure_metadata.position must be at least 1
  • exposure_metadata.visibility_ms must be at least 0