Cast Analytics API Documentation

Prerequisites

To use the Cast API, you’ll need an API key and the following variables.

  • API Key: Request yours by emailing support@cast.app.
  • Find the org_slug, cast_id, and generate_group_id (campaign id) from the URL when you are viewing a specific campaign.

URL: https://cast.app/designer/{org_slug}/cast/{cast_id}/campaign/{campaign_id}/analytics

Example: https://cast.app/designer/45ac8dse/cast/11432/campaign/2392/analytics

Making Requests

Use this base URL for requests: https://cast.app/designer/{org_slug}/api. Add the endpoint and required parameters to the base URL.

1. Get Analytics Summary

This endpoint allows you to retrieve analytic summary for a specific cast and generation.

Endpoint 

GET /cast/{cast_id}/generation/{generation_id}/analytics

Path Parameters

  • cast_id (required): The ID of the cast.
  • generation_id (required): The ID of the generation or campaign (Identified in UI as Campaign ID).

Headers

  • Authorization (required): Your API key. Set it as your_api_key.

Example Request 

GET /designer/46ca7ead/api/cast/1940/generation/20221220_ABzeiySNDkrgW6sZ6UNkpC/analytics HTTP/1.1
Host: cast.app
Authorization: gBByzd$FiDnX#KMwq6!di&GiS&Qi!jsV

Example Response 

{
  "summary": {
    "unique_view": 3,
    "unique_play": 0,
    "unique_action": 0,
    "unique_feedback": 0,
    "total_view": 7,
    "total_play": 0,
    "total_action": 0,
    "total_feedback": 0
  },
  "timeline": {
    "items": {
      "view": [
        {
          "event_dt": "2022-12-20T13:00:00",
          "count": 5
        },
        {
          "event_dt": "2022-12-20T17:00:00",
          "count": 1
        },
        {
          "event_dt": "2022-12-20T22:00:00",
          "count": 1
        }
      ]
    },
    "frequency": "1H",
    "dt_min": "2022-12-20T13:00:00",
    "dt_max": "2022-12-20T22:00:00"
  },
  "scenes_watched": [],
  "actions_clicked": [],
  "feedbacks": [],
  "user_agents": {
    "mobile": {
      "count": 0,
      "orientation": {
        "portrait": 0,
        "landscape": 0
      }
    },
    "desktop": {
      "count": 3,
      "orientation": {
        "portrait": 0,
        "landscape": 3
      }
    }
  },
  "languages": {
    "english": 3
  }
}

2. Get Analytics Events

This endpoint allows you to retrieve analytic events for a specific cast and generation.

Endpoint 

GET /cast/{cast_id}/generation/{generation_id}/analytics_events

Path Parameters

  • cast_id (required): The ID of the cast.
  • generation_id (required): The ID of the generation/campaign.

Query Parameters

  • event_type (required): The type of event. Choose one of the following options:
    • delivered: Delivered events.
    • view: Cast viewed events (cast was opened).
    • play: Cast played events.
    • action: Recommendation click events.
    • feedback: Feedback events.
  • page (optional): The page of results. The default is 1.
  • page_size (optional): The number of results per page. The default is 50.

Headers

  • Authorization (required): Your API key. Set it as your_api_key.

Example Request 

GET /designer/46ca7ead/api/cast/1940/generation/20221220_ABzeiySNDkrgW6sZ6UNkpC/analytics_events?page_size=200&event_type=view HTTP/1.1
Host: cast.app
Authorization: gBByzd$FiDnX#KMwq6!di&GiS&Qi!jsV

Example Response 

{
  "count": 7,
  "page": 1,
  "page_size": 200,
  "results": [
    {
      "event_at": "2022-12-20T22:54:33",
      "ip_address": "49.44.82.138",
      "event_type": "view",
      "contact_id": "1443653",
      "contact_email": "hardik+mike@cast.app",
      "contact_name": "Mike",
      "contact_phone": "810-374-9840",
      "device_type": "desktop",
      "os_name": "Windows",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T17:11:45",
      "ip_address": "49.44.67.197",
      "event_type": "view",
      "contact_id": "1443657",
      "contact_email": "hardik+yolanda@cast.app",
      "contact_name": "Yolanda",
      "contact_phone": "419-800-6759",
      "device_type": "desktop",
      "os_name": "Windows",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T13:57:28",
      "ip_address": "182.79.253.133",
      "event_type": "view",
      "contact_id": "1443654",
      "contact_email": "hardik+karen@cast.app",
      "contact_name": "Karen",
      "contact_phone": "856-264-4130",
      "device_type": "desktop",
      "os_name": "Windows",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T13:57:21",
      "ip_address": "2a09:bac1:36e0:18::1c5:2e",
      "event_type": "view",
      "contact_id": "1443654",
      "contact_email": "hardik+karen@cast.app",
      "contact_name": "Karen",
      "contact_phone": "856-264-4130",
      "device_type": "desktop",
      "os_name": "macOS",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T13:57:18",
      "ip_address": "49.44.82.164",
      "event_type": "view",
      "contact_id": "1443657",
      "contact_email": "hardik+yolanda@cast.app",
      "contact_name": "Yolanda",
      "contact_phone": "419-800-6759",
      "device_type": "desktop",
      "os_name": "Windows",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T13:57:13",
      "ip_address": "2a09:bac1:36e0:18::1c5:2e",
      "event_type": "view",
      "contact_id": "1443657",
      "contact_email": "hardik+yolanda@cast.app",
      "contact_name": "Yolanda",
      "contact_phone": "419-800-6759",
      "device_type": "desktop",
      "os_name": "macOS",
      "browser_name": "Chrome",
      "status": "active"
    },
    {
      "event_at": "2022-12-20T13:56:37",
      "ip_address": "42.106.161.5",
      "event_type": "view",
      "contact_id": "1443653",
      "contact_email": "hardik+mike@cast.app",
      "contact_name": "Mike",
      "contact_phone": "810-374-9840",
      "device_type": "desktop",
      "os_name": "Windows",
      "browser_name": "Chrome",
      "status": "active"
    }
  ]
}

Notes

Make sure to replace your_org_slug with your organization’s slug and your_api_key with your actual API key in the example requests.

Example Video