# Retention

> Track how users progress, return and drop off over their lifetime.

Retention endpoints read each user's whole history, so the web app calls them without a date window. They share the [Analytics](/reference/admin-analytics/) filters and the same `429` retry behaviour.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /admin/dashboard/time-to-launch`: Retrieve time to launch
- `GET /admin/dashboard/churn`: Retrieve churn
- `GET /admin/dashboard/churn/users`: List churned users
- `GET /admin/dashboard/cohorts`: Retrieve signup cohorts
- `GET /admin/dashboard/cohorts/users`: List a cohort's users
- `GET /admin/dashboard/stickiness`: Retrieve stickiness

### Retrieve time to launch

`GET /admin/dashboard/time-to-launch`

Returns how many users reached each launch-count milestone, by days since signup. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.
- `milestones` (string, optional): Comma-separated launch counts, such as `1,5,10`.
- `max_days` (integer, optional): Days after signup to cover.

#### Returns 200 OK

- `max_days` (integer): Days covered.
- `total_users` (integer): Users counted.
- `active_users` (integer): Users with at least one launch.
- `milestones` (array<object>): One entry per milestone.
  - `milestone` (integer): Launch count.
  - `reached` (integer): Users who ever reached it.
  - `cumulative` (array<integer>): Index is days after signup; value is users who had reached it by then.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid milestones: <milestones>` | `milestones` is not a comma-separated list of launch counts. More than 20 milestones answers `at most 20 milestones`. | Send up to 20 comma-separated launch counts, such as `1,5,10`. |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/time-to-launch" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "max_days": 30,
  "total_users": 1630,
  "active_users": 211,
  "milestones": [
    {
      "milestone": 1,
      "reached": 211,
      "cumulative": [
        58,
        97,
        121,
        140
      ]
    }
  ]
}
```

### Retrieve churn

`GET /admin/dashboard/churn`

Returns users grouped by days since their last launch. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.

#### Returns 200 OK

- `buckets` (array<object>): Inactivity buckets.
  - `label` (string): Bucket label.
  - `min_days` (integer): Lower bound, in days.
  - `max_days` (integer | null): Upper bound, in days. `null` for the last bucket.
  - `user_count` (integer): Users in the bucket.
- `currency` (enum): Unit applied to the money amounts. Possible values: `usd`, `native`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid currency: <currency>` | `currency` is not `usd` or `native`. | Send `currency=usd` or `currency=native`. |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/churn" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "buckets": [
    {
      "label": "1-7d",
      "min_days": 1,
      "max_days": 7,
      "user_count": 48
    },
    {
      "label": "90d+",
      "min_days": 90,
      "max_days": null,
      "user_count": 61
    }
  ],
  "currency": "usd"
}
```

### List churned users

`GET /admin/dashboard/churn/users`

Returns the users in an inactivity range, with their last launch. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.
- `min_days` (integer, required): Minimum days since the last launch.
- `max_days` (integer, optional): Maximum days since the last launch.
- `limit` (integer, optional): Page size.
- `offset` (integer, optional): Number of rows to skip.
- `sort` (enum, optional): Sort key. Possible values: `username`, `inactive`, `launches`, `revenue`, `pnl`.
- `order` (enum, optional): Sort direction. `desc` is biggest first. Possible values: `asc`, `desc`.

#### Returns 200 OK

- `users` (array<object>): Users.
  - `license_key` (string): License key.
  - `username` (string): Username.
  - `days_since_last_launch` (integer): Days since the last launch.
  - `total_launches` (integer): Lifetime launches.
  - `total_revenue_gross` (string): Lifetime fees paid, in the requested `currency` (micro-USD, or lamports or wei), as an integer string.
  - `total_pnl` (string): Lifetime launch P&L, in the requested `currency` (micro-USD, or lamports or wei), as an integer string.
  - `last_launch` (object): Last launch: `name`, `symbol`, `image_url`, `launched_at` (Unix seconds), `revenue_gross`, `pnl`.
- `total` (integer): Total matching users.
- `limit` (integer): Applied page size.
- `offset` (integer): Applied offset.
- `currency` (enum): Unit applied to the money amounts. Possible values: `usd`, `native`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid currency: <currency>` | `currency` is not `usd` or `native`. | Send `currency=usd` or `currency=native`. |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/churn/users?min_days=%3Cmin_days%3E" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "users": [
    {
      "license_key": "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp",
      "username": "sampledev",
      "days_since_last_launch": 12,
      "total_launches": 9,
      "total_revenue_gross": "1840000000",
      "total_pnl": "-120000000",
      "last_launch": {
        "name": "Sample Token",
        "symbol": "SMPL",
        "image_url": null,
        "launched_at": 1791380400,
        "revenue_gross": "210000000",
        "pnl": "45000000"
      }
    }
  ],
  "total": 48,
  "limit": 50,
  "offset": 0,
  "currency": "usd"
}
```

### Retrieve signup cohorts

`GET /admin/dashboard/cohorts`

Returns retention per monthly signup cohort. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.
- `hide_inactive` (boolean, optional): Leaves out users who never launched.

#### Returns 200 OK

- `windows` (array<object>): Retention windows: `label`, `start_days`, `end_days` (days after signup).
- `cohorts` (array<object>): One entry per signup month.
  - `cohort` (string): Signup month, `YYYY-MM` (UTC).
  - `start_at` (integer): Month start, Unix seconds.
  - `user_count` (integer): Users in the cohort.
  - `retention` (array<object>): Per window, in the order of `windows`: `eligible`, `active`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/cohorts" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "windows": [
    {
      "label": "D1",
      "start_days": 0,
      "end_days": 1
    },
    {
      "label": "D7",
      "start_days": 1,
      "end_days": 7
    }
  ],
  "cohorts": [
    {
      "cohort": "2026-09",
      "start_at": 1788220800,
      "user_count": 132,
      "retention": [
        {
          "eligible": 132,
          "active": 41
        },
        {
          "eligible": 132,
          "active": 29
        }
      ]
    }
  ]
}
```

### List a cohort's users

`GET /admin/dashboard/cohorts/users`

Returns the users of one signup cohort with their launches per window. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.
- `hide_inactive` (boolean, optional): Leaves out users who never launched.
- `cohort` (string, required): Signup month, `YYYY-MM`.
- `limit` (integer, optional): Page size. The web app asks for 2000.
- `offset` (integer, optional): Number of rows to skip.

#### Returns 200 OK

- `windows` (array<object>): Retention windows: `label`, `start_days`, `end_days` (days after signup).
- `users` (array<object>): Users.
  - `license_key` (string): License key.
  - `username` (string): Username.
  - `created_at` (integer): Signup time, Unix seconds.
  - `total_launches` (integer): Lifetime launches.
  - `last_launch_at` (integer | null): Last launch time, Unix seconds.
  - `launches` (array<integer>): Launches per window, in the order of `windows`.
- `total` (integer): Total users in the cohort.
- `limit` (integer): Applied page size.
- `offset` (integer): Applied offset.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid cohort: <cohort>` | `cohort` is not a month in `YYYY-MM` form. | Send `cohort` as `YYYY-MM`, such as `2026-09`. |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/cohorts/users?cohort=%3Ccohort%3E" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "windows": [
    {
      "label": "D1",
      "start_days": 0,
      "end_days": 1
    },
    {
      "label": "D7",
      "start_days": 1,
      "end_days": 7
    }
  ],
  "users": [
    {
      "license_key": "SAMPLEDEV-Hy6Rk1Ws9Jd3Fq8Lp",
      "username": "sampledev",
      "created_at": 1788500000,
      "total_launches": 9,
      "last_launch_at": 1791380400,
      "launches": [
        2,
        3
      ]
    }
  ],
  "total": 132,
  "limit": 2000,
  "offset": 0
}
```

### Retrieve stickiness

`GET /admin/dashboard/stickiness`

Returns active users per short period against active users per longer period. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

For example `numerator=day` and `denominator=month` gives daily over monthly active users.

#### Query parameters

- `chain_id` (enum, optional): Restricts to one chain. `all` is not sent. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `currency` (enum, optional, default "usd"): Unit of the money amounts. The web app offers `native` only with a `chain_id`. Possible values: `usd`, `native`.
- `include_archived` (boolean, optional, default "true"): Counts archived launches.
- `count_group_members` (boolean, optional, default "false"): Counts launches that belong to a launch group.
- `utc_offset` (integer, optional): Offset from UTC, in hours, for bucket boundaries. The web app leaves it out for UTC+1.
- `numerator` (enum, optional): Short period. Possible values: `day`, `week`, `month`, `year`, `all`.
- `denominator` (enum, optional): Long period. Possible values: `day`, `week`, `month`, `year`, `all`.

#### Returns 200 OK

- `numerator` (enum): Short period applied. Possible values: `day`, `week`, `month`, `year`, `all`.
- `denominator` (enum): Long period applied. Possible values: `day`, `week`, `month`, `year`, `all`.
- `points` (array<object>): One point per short period.
  - `period_start` (integer): Short period start, Unix seconds.
  - `active_users` (integer): Users with a launch in the short period.
  - `denominator_period_start` (integer): Enclosing long period start, Unix seconds.
  - `denominator_active_users` (integer): Users with a launch in the long period.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid period: <period>` | `numerator` or `denominator` is not a known period. | Send `day`, `week`, `month`, `year` or `all`. |
| 429 | `too_many_requests` | `analytics are busy, retry in a minute` | All analytics slots stayed busy for 45 seconds: the API runs at most three analytics computations at once. The web app retries with exponential backoff (2 s doubling, capped at 30 s, up to 8 retries). | Retry with exponential backoff. |
| 429 | `too_many_requests` | `analytics are computing, retry in a minute` | The aggregate ran past the 60-second analytics limit and was stopped. The API serves its last answer for the same query instead when it has one from the past hour, so this means it has none. | Retry with exponential backoff, and narrow the query, for example to one `chain_id`, if it keeps failing. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/dashboard/stickiness" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "numerator": "day",
  "denominator": "month",
  "points": [
    {
      "period_start": 1792281600,
      "active_users": 38,
      "denominator_period_start": 1790812800,
      "denominator_active_users": 164
    }
  ]
}
```
