> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

# 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.

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678"
```

**Output:**

```json theme={null} theme={null}
{
  "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.

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
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:

```json theme={null} theme={null}
{
  "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:

```bash theme={null} theme={null}
asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678"
```

### Table

Human-readable table format:

```bash theme={null} theme={null}
asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678" \
  --output table
```

### Markdown

Markdown tables for documentation:

```bash theme={null} theme={null}
asc insights weekly \
  --app "123456789" \
  --source sales \
  --week "2026-02-16" \
  --vendor "12345678" \
  --output markdown
```

## Common Workflows

### Weekly Performance Dashboard

```bash theme={null} theme={null}
#!/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

```bash theme={null} theme={null}
# 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
```

## Related Commands

* [Analytics](/commands/analytics) - Download raw analytics and sales reports
* [Finance](/commands/finance) - Financial reports and payment data
* [Subscriptions](/commands/subscriptions) - Manage subscription products and pricing

## API Reference

* [Sales Reports](https://sosumi.ai/documentation/appstoreconnectapi/download_sales_and_trends_reports)
* [Analytics Reports](https://sosumi.ai/documentation/appstoreconnectapi/analyticsreport)
* [Apps](https://sosumi.ai/documentation/appstoreconnectapi/app)