---
name: ainative-growth-metrics
description: AINative growth metrics and investor reporting skill. Use when (1) Checking DAU/MAU numbers, (2) Pulling growth metrics for investor updates, (3) Analyzing model usage and popularity, (4) Reviewing user retention cohorts, (5) Understanding tier/conversion breakdown, (6) Generating growth reports. Queries the admin growth API endpoints on api.ainative.studio.
---

# AINative Growth Metrics

## Overview

This skill provides access to AINative CLI growth metrics for investor reporting,
growth research, and product analytics. Data is sourced from CLI telemetry events
stored in the platform database.

> **Data gap, 2026-05-19 to 2026-09-07:** the ingestion/aggregation pipeline
> behind these endpoints was broken for this period (two separate bugs — a
> `user_id` UUID-cast failure on unauthenticated events, and a text/uuid
> `COALESCE` type error in the DAU/MAU query — both silently swallowed by
> exception handlers, so the API returned clean `200`s with zero data
> instead of erroring). Fixed and verified end-to-end in
> [core#7056](https://github.com/AINative-Studio/core/pull/7056) and
> [core#7057](https://github.com/AINative-Studio/core/pull/7057). Treat any
> DAU/MAU/session/model/retention numbers from that window as missing, not
> zero-usage. Full writeup: `docs/bugs/GROWTH_METRICS_EMPTY.md` in cody-cli.

## API Endpoints

All endpoints require admin authentication via `x-api-key` header with an admin-level API key.

### 1. Growth Summary

```
GET https://api.ainative.studio/api/v1/admin/growth/cli-metrics?days=30
```

**Auth:** `x-api-key: sk_...` (admin)

**Query params:**
- `days` (7-90, default 30) — lookback window

**Returns:**
```json
{
  "period": "2026-07-08 to 2026-08-07",
  "dau_today": 142,
  "dau_yesterday": 138,
  "dau_7d_avg": 135.4,
  "mau_current": 2847,
  "mau_previous": 2103,
  "mau_growth_pct": 35.4,
  "total_sessions_7d": 4200,
  "total_sessions_30d": 18500,
  "avg_session_duration_sec": 342.5,
  "new_users_7d": 89,
  "new_users_30d": 412,
  "tier_breakdown": [
    {"tier": "free", "count": 2100, "percentage": 73.8},
    {"tier": "pro", "count": 580, "percentage": 20.4},
    {"tier": "basic", "count": 120, "percentage": 4.2},
    {"tier": "enterprise", "count": 47, "percentage": 1.6}
  ],
  "dau_trend": [
    {"date": "2026-07-08", "count": 110},
    {"date": "2026-07-09", "count": 125}
  ],
  "top_models": [
    {"model": "deepseek-4-flash", "requests": 12500, "unique_users": 890},
    {"model": "kimi-k3", "requests": 8200, "unique_users": 620}
  ]
}
```

**Key metrics for investors:**
- **DAU/MAU ratio** — healthy is 20%+ (stickiness)
- **MAU growth %** — month-over-month user growth
- **Free → paid conversion** — tier_breakdown shows paid % of MAU
- **New users** — top-of-funnel velocity

### 2. Model Usage Detail

```
GET https://api.ainative.studio/api/v1/admin/growth/cli-metrics/models?days=30
```

**Returns per-model breakdown:**
```json
{
  "period": "last 30 days",
  "models": [
    {
      "model": "deepseek-4-flash",
      "total_requests": 12500,
      "unique_users": 890,
      "successes": 12300,
      "errors": 200,
      "error_rate_pct": 1.6,
      "avg_latency_ms": 1200
    }
  ]
}
```

**Investor angle:** Shows which models drive engagement, provider diversity,
and reliability (error rates).

### 3. Retention Cohorts

```
GET https://api.ainative.studio/api/v1/admin/growth/cli-metrics/retention?weeks=8
```

**Returns weekly retention cohort table:**
```json
{
  "weeks_lookback": 8,
  "cohorts": [
    {
      "cohort_week": "2026-06-16",
      "cohort_size": 150,
      "week_1": 62.0,
      "week_2": 45.3,
      "week_3": 38.7,
      "week_4": 35.1
    }
  ]
}
```

**Reading retention:** Week 1 = 62% means 62% of users who signed up in that week
came back the following week. Healthy developer tools target 40%+ W1 retention.

## CLI Telemetry Event Types

The growth metrics are computed from these CLI events:

| Event | What it measures |
|-------|-----------------|
| `zerotime_init` | Session start → DAU/MAU (distinct `user_id` per day/month) |
| `zerotime_exit` | Session end → duration (`properties.uptime`) |
| `zerotime_api_success` | Successful model call → model popularity, success rate |
| `zerotime_api_error` | Failed model call → error rates, reliability |

**User identification:**
- `user_id` — UUID from auth, or `anonymous` for unauthenticated
- `device_id` — stable per-device hash (available in `properties`)
- `subscription_type` — from event metadata, used for tier tracking

## Generating Investor Reports

When asked to generate a growth report, follow this template:

### AINative Growth Report — [Month Year]

**Headline Metrics:**
- DAU: [dau_today] (7d avg: [dau_7d_avg])
- MAU: [mau_current] ([mau_growth_pct]% MoM)
- DAU/MAU ratio: [dau_7d_avg / mau_current * 100]%
- New users (30d): [new_users_30d]

**Engagement:**
- Total sessions (30d): [total_sessions_30d]
- Avg session duration: [avg_session_duration_sec / 60] minutes
- Sessions per DAU: [total_sessions_30d / mau_current]

**Conversion & Revenue:**
- Free users: [free count] ([free %]%)
- Paid users: [sum of non-free] ([100 - free %]%)
- Conversion rate: [paid / total * 100]%

**Model Usage:**
- Top model: [top_models[0].model] ([requests] requests, [unique_users] users)
- Model diversity: [count of models with >100 requests]

**Retention (latest cohort):**
- W1: [week_1]%
- W4: [week_4]%

## Usage Examples

```bash
# Quick DAU/MAU check
curl -s -H "x-api-key: $AINATIVE_ADMIN_KEY" \
  "https://api.ainative.studio/api/v1/admin/growth/cli-metrics" | jq '{dau_today, mau_current, mau_growth_pct}'

# Model popularity
curl -s -H "x-api-key: $AINATIVE_ADMIN_KEY" \
  "https://api.ainative.studio/api/v1/admin/growth/cli-metrics/models?days=7" | jq '.models[:5]'

# Retention for last 4 weeks
curl -s -H "x-api-key: $AINATIVE_ADMIN_KEY" \
  "https://api.ainative.studio/api/v1/admin/growth/cli-metrics/retention?weeks=4"
```