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

3. Get Campaign List

This endpoint allows you to retrieve a list of campaigns for a specific project.

Endpoint

GET https://cast.app/designer/<ORG_SLUG>/api/cast/<PROJECT_ID>/generation

Headers

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

Path Parameters

• ORG_SLUG (required): Your organization’s slug.
• PROJECT_ID (required): The ID of the project for which you want to retrieve campaigns

Example Request

GET https://cast.app/designer/acme-corp/api/cast/12345/generation HTTP/1.1
Host: cast.app
Authorization: 3jH4kL7p89NQ5dGhT6jUy

Response

The response is an array of campaign objects. Each object contains the following fields:

| Field                      | Type    | Description                                       |
| -------------------------- | ------- | ------------------------------------------------- |
| id                         | integer | The unique identifier for the campaign            |
| org_id                     | integer | The organization ID                               |
| cast_id                    | integer | The project ID                                    |
| name                       | string  | The name of the campaign                          |
| generate_group             | string  | A unique identifier for the generation group      |
| PROCESSING                 | integer | Number of items in processing state               |
| FINISHED                   | integer | Number of items in finished state                 |
| FAILED                     | integer | Number of items in failed state                   |
| SKIPPED                    | integer | Number of items in skipped state                  |
| TOTAL                      | integer | Total number of items                             |
| error_message              | string  | Error message if any                              |
| status                     | string  | Current status of the campaign (e.g., "FINISHED") |
| is_archived                | boolean | Whether the campaign is archived                  |
| created_at                 | string  | Timestamp of campaign creation (ISO 8601 format)  |
| delivery_reminders         | array   | Delivery reminders for the campaign               |
| delivery_date              | string  | Delivery date of the campaign                     |
| scheduled_delivery_id      | string  | Scheduled delivery ID                             |
| scheduled_delivery_date    | string  | Scheduled delivery date                           |
| schedule_delivery_occurred | boolean | Whether the scheduled delivery occurred           |

Example Response

[
  {
    "id": 4139,
    "org_id": 432,
    "cast_id": 1955,
    "name": "ANZ",
    "generate_group": "20240805_UZ7nBjQLwss863cw7YSr5B",
    "condition_data": {
      "conditions": [],
      "how": null,
      "type": "enable"
    },
    "PROCESSING": 0,
    "FINISHED": 1,
    "FAILED": 0,
    "SKIPPED": 0,
    "TOTAL": 1,
    "error_message": null,
    "status": "FINISHED",
    "is_archived": false,
    "created_at": "2024-08-05T15:43:15.077Z",
    "delivery_reminders": [],
    "delivery_date": null,
    "scheduled_delivery_id": null,
    "scheduled_delivery_date": null,
    "schedule_delivery_occurred": false
  },
  {
    "id": 1923,
    "org_id": 432,
    "cast_id": 1955,
    "name": "MUFG July 2023",
    "generate_group": "20230721_8Bv2eyE5SMCSKhx2EXmXrG",
    "condition_data": {
      "conditions": [],
      "how": null,
      "type": "enable"
    },
    "PROCESSING": 0,
    "FINISHED": 7,
    "FAILED": 0,
    "SKIPPED": 0,
    "TOTAL": 7,
    "error_message": null,
    "status": "FINISHED",
    "is_archived": false,
    "created_at": "2023-07-21T04:06:47.059Z",
    "delivery_reminders": [],
    "delivery_date": null,
    "scheduled_delivery_id": null,
    "scheduled_delivery_date": null,
    "schedule_delivery_occurred": false
  }
]

Notes

• The id field in the response represents the campaign ID.
• The cast_id field represents the project ID.
• The name field contains the campaign name.
• The status field indicates the current status of the campaign.

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