Skip to main content
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

​
API Reference