Insights

Generate weekly and daily insights from App Store data sources

The insights command generates actionable metrics and comparisons from App Store analytics and sales data, helping you track app performance over time.

Overview

Insights commands analyze your app’s data to provide:

Week-over-week comparisons - Compare current week metrics to previous week
Day-over-day comparisons - Track daily changes in subscription renewals
Multiple data sources - Combine analytics metadata and sales reports
App-scoped metrics - Automatically filter for your app and linked in-app purchases

Weekly Insights

Compare metrics between the current week and the previous week.

asc insights weekly \
  --app "123456789" \
  --source analytics \
  --week "2026-02-16"

Required Flags:

--app - App ID (or ASC_APP_ID env)
--source - Data source: analytics or sales
--week - Week start date (YYYY-MM-DD, Monday)

Source-Specific Requirements:

sales: Requires --vendor (or ASC_VENDOR_NUMBER env)

Optional Flags:

--output - Output format: json (default), table, markdown
--pretty - Pretty-print JSON output

Analytics Source

Provides metadata-based insights from analytics report requests: Metrics:

completed_requests - Number of completed analytics requests
reports_available - Number of unique reports available
instances_available - Number of report instances available
business_conversion_rate - Not derivable (marked unavailable)

Example:

asc insights weekly \
  --app "123456789" \
  --source analytics \
  --week "2026-02-16" \
  --output table

Output:

Context
┌──────────────────┬─────────────────────────┐
│ field            │ value                   │
├──────────────────┼─────────────────────────┤
│ appId            │ 123456789               │
│ source           │ analytics               │
│ week             │ 2026-02-16 to 2026-02-22│
│ previousWeek     │ 2026-02-09 to 2026-02-15│
│ requestsScanned  │ 42                      │
└──────────────────┴─────────────────────────┘

Metrics
┌────────────────────────┬────────┬──────────┬──────────┬───────┬─────────────┬────────┐
│ metric                 │ unit   │ thisWeek │ lastWeek │ delta │ deltaPercent│ status │
├────────────────────────┼────────┼──────────┼──────────┼───────┼─────────────┼────────┤
│ completed_requests     │ count  │ 5.00     │ 3.00     │ 2.00  │ 66.67       │ ok     │
│ reports_available      │ count  │ 12.00    │ 10.00    │ 2.00  │ 20.00       │ ok     │
│ instances_available    │ count  │ 84.00    │ 70.00    │ 14.00 │ 20.00       │ ok     │
└────────────────────────┴────────┴──────────┴──────────┴───────┴─────────────┴────────┘

Sales Source

Provides transaction-level insights from sales reports: Metrics:

download_units - App downloads (free or paid)
monetized_units - Units with revenue (app + IAP/subscriptions linked to app)
units - Total units across all transaction types
developer_proceeds - Total developer proceeds
customer_price - Total customer price
report_rows - Number of sales report rows processed
active_devices - Not derivable (marked unavailable)

App Scoping: Sales insights automatically scope to:

Rows where Apple Identifier matches the app ID (for downloads)
Rows where Parent Identifier matches the app SKU or app ID (for IAP/subscriptions)

Example:

asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678"

Output:

{
  "appId": "123456789",
  "source": {
    "name": "sales",
    "vendorNumber": "12345678",
    "appSku": "com.example.myapp"
  },
  "week": {
    "start": "2026-02-16",
    "end": "2026-02-22"
  },
  "previousWeek": {
    "start": "2026-02-09",
    "end": "2026-02-15"
  },
  "metrics": [
    {
      "name": "download_units",
      "unit": "count",
      "thisWeek": 1234.00,
      "lastWeek": 1100.00,
      "delta": 134.00,
      "deltaPercent": 12.18,
      "status": "ok"
    },
    {
      "name": "monetized_units",
      "unit": "count",
      "thisWeek": 456.00,
      "lastWeek": 420.00,
      "delta": 36.00,
      "deltaPercent": 8.57,
      "status": "ok"
    },
    {
      "name": "developer_proceeds",
      "unit": "currency",
      "thisWeek": 3456.78,
      "lastWeek": 3200.50,
      "delta": 256.28,
      "deltaPercent": 8.01,
      "status": "ok"
    }
  ]
}

Daily Insights

Track day-over-day changes in subscription renewal metrics.

asc insights daily \
  --app "123456789" \
  --vendor "12345678" \
  --date "2026-02-20"

Required Flags:

--app - App ID (or ASC_APP_ID env)
--vendor - Vendor number (or ASC_VENDOR_NUMBER env)
--date - Report date (YYYY-MM-DD)

Optional Flags:

--output - Output format: json (default), table, markdown

Metrics:

renewal_rows - Count of rows where Subscription contains “Renewal”
renewal_units - Units from renewal rows
renewal_developer_proceeds - Developer proceeds from renewals
subscription_rows - Count of rows with subscription data
subscription_units - Units from subscription rows
subscription_developer_proceeds - Developer proceeds from subscriptions
monetized_units - Total units with revenue (app + linked IAP/subscriptions)
report_rows - Total rows processed

Example:

asc insights daily \
  --app "123456789" \
  --vendor "12345678" \
  --date "2026-02-20" \
  --output table

Output:

Context
┌──────────────┬────────────────────┐
│ field        │ value              │
├──────────────┼────────────────────┤
│ appId        │ 123456789          │
│ source       │ sales              │
│ date         │ 2026-02-20         │
│ previousDate │ 2026-02-19         │
│ vendorNumber │ 12345678           │
│ reportType   │ SALES              │
│ frequency    │ DAILY              │
└──────────────┴────────────────────┘

Metrics
┌──────────────────────────────┬──────────┬─────────┬─────────────┬───────┬─────────────┬────────┐
│ metric                       │ unit     │ thisDay │ previousDay │ delta │ deltaPercent│ status │
├──────────────────────────────┼──────────┼─────────┼─────────────┼───────┼─────────────┼────────┤
│ renewal_rows                 │ count    │ 42.00   │ 38.00       │ 4.00  │ 10.53       │ ok     │
│ renewal_units                │ count    │ 42.00   │ 38.00       │ 4.00  │ 10.53       │ ok     │
│ renewal_developer_proceeds   │ currency │ 245.00  │ 220.00      │ 25.00 │ 11.36       │ ok     │
│ subscription_rows            │ count    │ 58.00   │ 52.00       │ 6.00  │ 11.54       │ ok     │
└──────────────────────────────┴──────────┴─────────┴─────────────┴───────┴─────────────┴────────┘

Understanding Metrics

Metric Status

ok - Metric calculated successfully with both current and previous period data
unavailable - Metric cannot be calculated (with reason in reason field)

Delta Calculations

delta - Absolute difference: thisWeek - lastWeek or thisDay - previousDay
deltaPercent - Percentage change: ((thisWeek - lastWeek) / lastWeek) * 100

Week Windows

Weeks run from Monday (start) through Sunday (end):

Week of 2026-02-16: 2026-02-16 (Mon) to 2026-02-22 (Sun)
Previous week: 2026-02-09 (Mon) to 2026-02-15 (Sun)

Data Availability

Analytics Source:

Requires existing analytics report requests for the app
Only counts completed requests within the week window
Reports unavailable if API key lacks analytics permissions

Sales Source:

Requires valid vendor number
Reports must be available for both the current and previous period
Weekly reports use the Sunday end date (e.g., 2026-02-22 for week ending Sunday)
Daily reports use the exact date specified

Handling Missing Data: If data is unavailable for one or both periods, metrics will show:

{
  "name": "metric_name",
  "unit": "count",
  "status": "unavailable",
  "reason": "this week: report not found"
}

Subscription Renewal Tracking

Daily insights identify renewal transactions by matching the Subscription column: Recognized renewal states:

Exact match: “Renewal” (case-insensitive)
Partial match: Any value containing “renew” (e.g., “Auto-Renew Subscription”)

Example sales report row:

Apple Identifier    Parent Identifier    Subscription    Units    Developer Proceeds
987654321           com.example.myapp    Renewal         1        4.99

This row contributes to both subscription_* and renewal_* metrics.

Output Formats

JSON (Default)

Deterministic, machine-readable output for automation:

asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678"

Table

Human-readable table format:

asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678" \
  --output table

Markdown

Markdown tables for documentation:

asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678" \
  --output markdown

Common Workflows

Weekly Performance Dashboard

#!/bin/bash
# Generate weekly insights for current week

WEEK_START=$(date -d 'last monday' +%Y-%m-%d)

# Sales metrics
asc insights weekly \
  --app "$ASC_APP_ID" \
  --source sales \
  --week "$WEEK_START" \
  --vendor "$ASC_VENDOR_NUMBER" \
  --output table

# Analytics metadata
asc insights weekly \
  --app "$ASC_APP_ID" \
  --source analytics \
  --week "$WEEK_START" \
  --output table

Daily Subscription Monitor

# Track yesterday's renewals
asc insights daily \
  --app "$ASC_APP_ID" \
  --vendor "$ASC_VENDOR_NUMBER" \
  --date "$(date -d yesterday +%Y-%m-%d)" \
  --output json > daily-renewals.json

Analytics - Download raw analytics and sales reports
Finance - Financial reports and payment data
Subscriptions - Manage subscription products and pricing

Overview

App Management

TestFlight & Builds

Monetization & Analytics

Signing

Review & Release

Team & Access

Automation & Utilities

Insights

Insights

Overview

Weekly Insights

Analytics Source

Sales Source

Daily Insights

Understanding Metrics

Metric Status

Delta Calculations

Week Windows

Data Availability

Subscription Renewal Tracking

Output Formats

JSON (Default)

Table

Markdown

Common Workflows

Weekly Performance Dashboard

Daily Subscription Monitor

API Reference

​Insights

​Overview

​Weekly Insights

​Analytics Source

​Sales Source

​Daily Insights

​Understanding Metrics

​Metric Status

​Delta Calculations

​Week Windows

​Data Availability

​Subscription Renewal Tracking

​Output Formats

​JSON (Default)

​Table

​Markdown

​Common Workflows

​Weekly Performance Dashboard

​Daily Subscription Monitor

​Related Commands

​API Reference

Insights

Overview

Weekly Insights

Analytics Source

Sales Source

Daily Insights

Understanding Metrics

Metric Status

Delta Calculations

Week Windows

Data Availability

Subscription Renewal Tracking

Output Formats

JSON (Default)

Table

Markdown

Common Workflows

Weekly Performance Dashboard

Daily Subscription Monitor

Related Commands

API Reference