REST API

The Cavai REST API provides programmatic access to reporting and analytics data. Use it to pull performance metrics, build custom dashboards, or integrate Cavai data into external tools.

Fair use

The API is provided for reasonable reporting and integration use. Excessive polling, high-frequency requests, or pulling large volumes of data unnecessarily may result in your access being restricted or revoked. If you're unsure whether your use case is appropriate, contact the Cavai team.

Base URLs

Cavai exposes two API services that share the same authentication token:

Service	Base URL	Purpose
Platform API	https://application-backend.cavai.com/api/v2	Reports, resource hierarchy
Analytics API	https://analytics-api.cavai.com/v2	Time-series metrics, counts, flow, domains

Authentication

API tokens (recommended)

Create a token in the Cavai Cloud UI:

1. Click your profile in the top navbar
2. Select Tokens from the left sidebar
3. Click New token

Include the token in all requests as a Bearer header:

Authorization: Bearer YOUR_TOKEN

Login-based auth

Alternatively, authenticate with email and password:

POST https://analytics-api.cavai.com/v2/login

{
  "email": "your@email.com",
  "password": "your-password"
}

The response includes session cookies to attach to future requests.

TIP

One token works for both services. Authenticate once and use the token with both the Platform API and the Analytics API.

Data tree

Before querying analytics, fetch the resource hierarchy to get the IDs you need.

GET https://application-backend.cavai.com/api/v2/campaigns/data_tree?workspaces[]=WORKSPACE_ID

Returns campaigns, creative groups, and creatives nested under each workspace:

{
  "data": [
    {
      "id": "1010",
      "name": "Winter campaign",
      "creativeGroups": [
        {
          "id": "2020",
          "name": "Video creatives",
          "creatives": [
            {
              "id": "3030",
              "name": "Feed slider"
            }
          ]
        }
      ]
    }
  ]
}

Use these IDs in the analytics endpoints below.

Reports

Reports are saved analytics views created in the Reports UI. You can also manage them via the API.

Method	Endpoint	Description
GET	/api/v2/reports	List all reports
GET	/api/v2/reports/:id	Get a report
POST	/api/v2/reports	Create a report
PUT	/api/v2/reports/:id	Update a report
DELETE	/api/v2/reports/:id	Delete a report
GET	/api/v2/workspaces/:workspace_id/reports	List reports in a workspace

Analytics queries

The Analytics API provides four read-only endpoints for querying metrics. All endpoints are under https://analytics-api.cavai.com/v2/aggregation-api/.

Buckets — time-series metrics

Returns metrics broken into time buckets (hourly, daily, weekly, or monthly).

GET /v2/aggregation-api/buckets

Parameter	Type	Required	Description
resource	string	Yes	"creative", "creative_group", or "campaign"
id	number[]	Yes	Resource IDs
time_from	string	Yes	Start date (ISO 8601, e.g. "2025-04-17T00:00:00.000Z")
time_to	string	Yes	End date
time_frame	string	Yes	Bucket size: "hour", "day", "week", or "month"
metric	string[]	Yes	Metrics to fetch (see available metrics)

Example — daily impressions and link clicks for two creatives:

GET /v2/aggregation-api/buckets?resource=creative&id[]=50717&id[]=50718&time_from=2025-04-17T00:00:00.000Z&time_to=2025-04-24T23:59:59.000Z&time_frame=day&metric[]=impressions&metric[]=link_clicks

{
  "50717": [
    { "id": 50717, "time": "2025-04-17 00:00:00", "impressions": 123, "link_clicks": 12 },
    { "id": 50717, "time": "2025-04-18 00:00:00", "impressions": 321, "link_clicks": 23 }
  ]
}

WARNING

This is a heavy endpoint. For quick lifetime totals, use Counts instead.

Counts — lifetime totals

Returns aggregate metrics for the entire lifetime of a resource. Fast and lightweight.

GET /v2/aggregation-api/counts

Parameter	Type	Required	Description
resource	string	Yes	"creative", "creative_group", or "campaign"
id	number[]	Yes	Resource IDs
metric	string[]	No	Metrics to fetch. Defaults to impressions, started, interacted.

Example:

GET /v2/aggregation-api/counts?resource=campaign&id[]=386

{
  "386": {
    "impressions": 53,
    "started": 4,
    "interacted": 9
  }
}

Flow — conversation analytics

Returns per-component analytics for conversational creatives — how users navigate through flow components.

GET /v2/aggregation-api/flow

Parameter	Type	Required	Description
creative_id	number[]	Yes	Creative IDs
time_from	string	No	Start date
time_to	string	No	End date

Example:

GET /v2/aggregation-api/flow?creative_id[]=50187

{
  "50187": [
    {
      "component_type": "Statement",
      "content": "Welcome to our quiz",
      "impressions": 14,
      "continue": 13,
      "drop": 1
    }
  ]
}

Domains — placement breakdown

Returns metrics broken down by the domains where creatives were served, including DSP information.

GET /v2/aggregation-api/domains

Parameter	Type	Required	Description
resource	string	Yes	"creative", "creative_group", or "campaign"
id	number[]	Yes	Resource IDs
time_from	string	Yes	Start date
time_to	string	Yes	End date

Example:

GET /v2/aggregation-api/domains?resource=creative_group&id[]=50217&time_from=2025-04-25T00:00:00.000Z&time_to=2025-05-02T23:59:59.000Z

{
  "50217": [
    {
      "domain": "example.com",
      "dsp": "DV360",
      "impressions": 7041,
      "interacted": 10,
      "link_clicks": 0
    }
  ]
}

CSV export is also available at /v2/aggregation-api/domains/csv with the same parameters.

Available metrics

The following metrics can be requested in the metric parameter:

Metric	Description
impressions	Total ad impressions served
viewable_impressions	Impressions that met viewability criteria
interacted	Users who interacted with the creative
started	Users who started the conversation flow
continued	Users who continued past the first flow component
reached_end	Users who reached the final flow component
creative_actions	Total in-creative actions
link_clicks	Clicks on links within the creative
header_clicks	Clicks on the creative header
background_clicks	Clicks on the creative background
plays	Video plays
watched_25	Users who watched 25% of video
watched_50	Users who watched 50% of video
watched_75	Users who watched 75% of video
watched_100	Users who watched 100% of video
seconds_to_active	Time until first interaction
seconds_total_active	Total active engagement time
seconds_in_view	Total time the creative was in the viewport

For detailed metric definitions, see Metrics.

TIP

Request only the metrics you need. Using base fetches all metrics but is slower.