Audience Insights & Channel Performance API Specification

This technical specification details the backend REST endpoints, request payloads, response schemas, and mathematical KPI formulas powering Audience Insights and the Channel Performance Grid in DriveMetaData.

1. Audience Insight API (`POST /api/v2/analytics/audiences/{id}/insight`)

Computes statistical audience profiling, historical volume trends, filter impact steps, and AI summary recommendations for a saved audience.

Request Specification

Endpoint: POST /api/v2/analytics/audiences/{audienceId}/insight

Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
Client-ID: 34507
Workspace-ID: 34509

Payload:

{
  "dateRange": ["2026-06-01", "2026-06-30"],
  "lookbackDays": 30,
  "includeComparisons": true
}

Response Schema (`data[0]`)

{
  "audienceId": "5001",
  "definitionVersion": 2,
  "confidence": "High",
  "estimatedSize": 14250,
  "purchasersPercent": 0.284,
  "averageOrderValue": 3450.00,
  "diagnostics": {
    "executionTime": "320ms",
    "queryHash": "sha256:insight-5001-v2"
  },
  "summaryCards": [
    {
      "id": "card-1",
      "title": "High Cart Intent Detected",
      "description": "28.4% of users in this audience completed an order within 7 days of cart addition.",
      "severity": "success",
      "recommendedActions": [
        "Sync to Meta Lookalike",
        "Trigger WhatsApp Abandoned Cart"
      ]
    },
    {
      "id": "card-2",
      "title": "Mobile Reachability Concentration",
      "description": "Over 74% of users interact primarily via Android and iOS devices.",
      "severity": "info",
      "recommendedActions": ["Enable Push Notification Channel"]
    }
  ],
  "trend": [
    { "label": "Run 1", "value": 11200 },
    { "label": "Run 2", "value": 12100 },
    { "label": "Run 3", "value": 13400 },
    { "label": "Run 4", "value": 14250 }
  ],
  "trendStats": {
    "current": 14250,
    "previous": 13400,
    "change": 850,
    "changePercent": 0.063,
    "confidence": "High"
  },
  "drivers": {
    "steps": [
      { "step": 1, "label": "Country = India", "count": 85000, "dropoffPercent": 0.0 },
      { "step": 2, "label": "Add to Cart (30d)", "count": 18600, "dropoffPercent": 0.781 },
      { "step": 3, "label": "NOT Purchased (30d)", "count": 14250, "dropoffPercent": 0.234, "final": true }
    ],
    "otherReasons": [
      { "label": "Email unsubscribed", "count": 420 },
      { "label": "Suppressed domain", "count": 130 }
    ]
  },
  "breakdowns": {
    "byCountry": [
      { "label": "India", "count": 11400, "share": 0.80 },
      { "label": "United Arab Emirates", "count": 1710, "share": 0.12 },
      { "label": "Singapore", "count": 1140, "share": 0.08 }
    ],
    "byCity": [
      { "label": "Bengaluru", "count": 4275, "share": 0.30 },
      { "label": "Mumbai", "count": 3562, "share": 0.25 },
      { "label": "Delhi", "count": 2850, "share": 0.20 }
    ],
    "byDevicePlatform": [
      { "label": "Android", "count": 8550, "share": 0.60 },
      { "label": "iOS", "count": 3990, "share": 0.28 },
      { "label": "Desktop", "count": 1710, "share": 0.12 }
    ],
    "byTrafficSource": [
      { "label": "Google Ads", "count": 6412, "share": 0.45 },
      { "label": "Meta Ads", "count": 4275, "share": 0.30 },
      { "label": "Direct / Organic", "count": 3563, "share": 0.25 }
    ],
    "byPublisher": [
      { "label": "Google Search", "count": 4987, "share": 0.35 },
      { "label": "Instagram", "count": 3562, "share": 0.25 },
      { "label": "YouTube", "count": 2850, "share": 0.20 }
    ]
  },
  "engagement": {
    "averageEventsPerUser": 14.2,
    "lastSeenBuckets": [
      { "label": "0 - 7 days", "count": 8550, "share": 0.60 },
      { "label": "8 - 14 days", "count": 3562, "share": 0.25 },
      { "label": "15 - 30 days", "count": 2138, "share": 0.15 }
    ]
  },
  "risk": {
    "reachabilityRate": 0.764,
    "flags": [
      {
        "code": "HIGH_DEVICE_FATIGUE",
        "severity": "warning",
        "message": "Audience received more than 4 ad impressions per user over the last 72 hours."
      }
    ]
  }
}

2. Channel Performance Cube API (`POST /api/v2/analytics/query`)

Queries the AttributionAdsPerformanceDaily analytical cube to power multi-channel attribution and ad ROI comparisons.

Request Payload

{
  "query": {
    "cube": "AttributionAdsPerformanceDaily",
    "dimensions": [
      "AttributionAdsPerformanceDaily.channel",
      "AttributionAdsPerformanceDaily.campaign",
      "AttributionAdsPerformanceDaily.country"
    ],
    "measures": [
      "AttributionAdsPerformanceDaily.spend",
      "AttributionAdsPerformanceDaily.revenue",
      "AttributionAdsPerformanceDaily.purchases",
      "AttributionAdsPerformanceDaily.impressions",
      "AttributionAdsPerformanceDaily.clicks"
    ],
    "time": [
      {
        "member": "AttributionAdsPerformanceDaily.date",
        "range": ["2026-06-01", "2026-06-30"],
        "granularity": "day"
      }
    ],
    "comparison": {
      "type": "previous_period"
    },
    "timezone": "Asia/Kolkata",
    "limit": 100,
    "offset": 0
  },
  "mode": "multi"
}

Supported Granularity Options

Parameter Value	Description
`"none"`	Aggregate totals across the entire date range without date breakdown.
`"day"`	Daily performance rows.
`"week"`	ISO calendar weekly rollups.
`"month"`	Monthly rollups.
`"quarter"`	Calendar quarterly rollups.
`"year"`	Annual totals.

Calculated Deltas & Directional Metrics

For comparative period requests, the backend evaluates the previous matching window and computes relative trends:

Spend Trend (%) = ((Current Spend - Previous Spend) / Previous Spend) * 100
Revenue Trend (%) = ((Current Revenue - Previous Revenue) / Previous Revenue) * 100
CPA Trend (%) = ((Current CPA - Previous CPA) / Previous CPA) * 100

For CPA Trend, an increase is flagged with cpaDirection: "up" (negative efficiency / cost increase).
A decrease in CPA is flagged with cpaDirection: "down" (improved efficiency).

3. UI Table Layout Preferences API (`/api/v2/users/preferences`)

The Channel Performance Table layout (dimensions, visible metrics, pinned columns, and granularity) is persisted per user and workspace.

Key: audience_builder_channel_performance_table_layout

Schema:

{
  "version": 1,
  "dimensions": ["channel", "campaign", "country", "device"],
  "metrics": ["spend", "revenue", "purchases", "ctr", "cvr", "cpaTrend"],
  "granularity": "day",
  "pinnedColumnIds": ["channel", "campaign"]
}

4. Mathematical KPI Formulas Glossary

Metric Name	Symbol	Mathematical Formula	Business Purpose
Cost Per Acquisition	`CPA`	`Spend / Purchases`	Quantifies the ad spend required to acquire a single paying customer.
Click-Through Rate	`CTR`	`(Clicks / Impressions) * 100`	Measures creative engagement and ad resonance.
Conversion Rate	`CVR`	`(Purchases / Clicks) * 100`	Measures landing page and checkout conversion velocity.
Return on Ad Spend	`ROAS`	`Attributed Revenue / Spend`	Gross financial return generated per dollar of advertising spend.
Average Order Value	`AOV`	`Total Revenue / Total Purchases`	Average revenue generated per transaction across this segment.
Reachability Rate	`RR`	`(Profiles with Verified Identifiers / Total Audience) * 100`	Percentage of an audience segment eligible for third-party ad sync.

1. Audience Insight API (POST /api/v2/analytics/audiences/{id}/insight)​

Request Specification​

Response Schema (data[0])​

2. Channel Performance Cube API (POST /api/v2/analytics/query)​

Request Payload​

Supported Granularity Options​

Calculated Deltas & Directional Metrics​

3. UI Table Layout Preferences API (/api/v2/users/preferences)​

4. Mathematical KPI Formulas Glossary​

Related Pages​