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 asyour_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 is1.page_size(optional): The number of results per page. The default is50.
Headers
Authorization(required): Your API key. Set it asyour_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.
4. Get Cross-Campaign Analytics
This endpoint allows you to fetch analytics summary for all campaigns in a project.
Endpoint
GET https://cast.app/designer/{ORG_SLUG}/api/cast/{PROJECT_ID}/cross_campaign_analytics_summary
Headers
Authorization(required): Your API key. Set it asyour_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 cross-campaign analytics.
Query Parameters
show_totals(optional): Whether to show total counts (default: true).
Example Request
GET https://cast.app/designer/about-cast/api/cast/2682/cross_campaign_analytics_summary?show_totals=true HTTP/1.1
Host: cast.app
Authorization: gBByzd$FiDnX#KMwq6!di&GiS&Qi!jsV
Response Fields
| Field | Type | Description |
|-----------------|---------|------------------------------|
| loadTime | integer | Number of views |
| play | integer | Number of plays |
| click.action | integer | Number of actions |
| feedback | integer | Number of feedback |
| email_delivered | integer | Number of emails delivered |
Example Response
{
"20241229_UntDSfEu5GSfpTHsbmVdHE": {
"loadTime": 2,
"play": 2,
"click.action": 0,
"feedback": 0,
"email_delivered": 0
},
"20241115_TsG47ABBeYFTdenHMrS4xP": {
"loadTime": 58,
"play": 12,
"click.action": 0,
"feedback": 0,
"email_delivered": 0
},
"20250119_SuN4WsvEYaVR6XXJWLZjvU": {
"loadTime": 268,
"play": 35,
"click.action": 0,
"feedback": 0,
"email_delivered": 0
}
}
In the response, each key represents a campaign identifier. To get total analytics across all campaigns, add up the values from each campaign in the response. For example, to calculate the total number of views, sum all the loadTime values from each 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.