Skip to main content Link Menu Expand (external link) Document Search Copy Copied

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