Loading API documentation...
v1.0.0
OAS 3.1.0

Pipelines API - Video Events

Video Semantic Events

This document describes semantic events for video tracking in the Customer.io Pipelines API.

Semantic events are special payloads for our track endpoint based on the event name. When you send a video event with a specific name (like Video Playback Started), Customer.io and downstream integrations recognize it and handle it appropriately.

With semantic events, you can set up your events and they'll work with any of our destinations that support video events.

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region Server Address
US https://cdp.customer.io
EU https://cdp-eu.customer.io

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.

Authentication

The Data Pipelines API uses basic authentication with your API key as the username and a blank password.

The base URL for all Data Pipelines calls in our United States (US) region.

No authentication selected
Client Libraries
Shell Curl

Track Video Event

​

Send video events to track playback, content, and ad interactions.

Video semantic events follow a standard structure for video analytics across different platforms.

Headers
  • X-Strict-Mode
    enum
    const:  
    1

    When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.

    values
    • 1
Body
required
application/json
      • userId
        Type: string
        required

        The unique identifier for the user.

      • type
        enum
        const:  
        track
        required

        The event type. Must be track for event calls.

        values
        • track
      • event
        enum
        const:  
        Video Playback Started
        required

        The event name. Must be Video Playback Started for this semantic event.

        values
        • Video Playback Started
      • properties
        required

        Properties describing video playback state and metadata.

        • session_id
          Type: string

          The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

        • ad_asset_id
        • ad_pod_id
        • ad_type
          Type: stringenum

          The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

          values
          • pre-roll
          • mid-roll
          • post-roll
        • position
          Type: integer

          The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

        • total_length
          Type: integer

          The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

        • bitrate
          Type: integer

          The current kbps.

        • framerate
          Type: integer

          The average frames per second (fps).

        • video_player
          Type: string

          The name of the video player the client uses, like youtube or vimeo.

        • sound
          Type: integer
          min:  
          0
          max:  
          100

          The current volume of the video player as a value between 1 and 100.

        • full_screen
          Type: boolean

          If true, playback is in fullscreen mode.

        • ad_enabled
          Type: boolean

          Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

        • quality
          Type: string

          The video quality of playback, like 480p or highres.

        • livestream
          Type: boolean

          Set to true if the playback is a livestream.

        • content_asset_ids
          Type: array string[]

          The ID of the videos a user started. The array indicates a potential playlist of videos/content IDs a person is starting.

        • content_pod_ids
          Type: array string[]

          The IDs of the content "pods" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. The array indicates a potential playlist of content pod IDs a person is starting.

        • propertyName
          Type: anything

          Additional custom properties for the event.

      • timestamp
        Type: stringFormat: date-time

        The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.

      • context
        Type: object · Context

        Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.

      • integrations
        Type: object · Integrations

        Control which integrations receive this event. By default, all enabled integrations receive events.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

Request Example for post/track
curl https://cdp.customer.io/v1/track \
  --request POST \
  --header 'X-Strict-Mode: 1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "userId": "user_12345",
  "type": "track",
  "event": "Video Playback Started",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "properties": {
    "session_id": "session_abc123",
    "ad_asset_id": "ad_asset_123",
    "ad_pod_id": "ad_pod_123",
    "ad_type": "pre-roll",
    "position": 120,
    "total_length": 3600,
    "bitrate": 5000,
    "framerate": 30,
    "video_player": "youtube",
    "sound": 75,
    "full_screen": false,
    "ad_enabled": true,
    "quality": "1080p",
    "livestream": false,
    "additionalProperty": null,
    "content_asset_ids": [
      "video_123",
      "video_456"
    ],
    "content_pod_ids": [
      "pod_123",
      "pod_456"
    ]
  },
  "context": {
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  }
}'

{}

A successful request returns an empty object response.

Models