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

# Reports API

> Access payback reports, cohort data, and growth metrics.

<Note>
  Reports are updated every 6 hours. For real-time event inspection, use the **Data → Events** view in the FloKit dashboard.
</Note>

***

## GET /v1/reports/payback

Returns payback report data for a given date range, grouped by the dimension of your choice.

### Query parameters

<ParamField query="start_date" type="string" required>
  Start of the cohort window. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="end_date" type="string" required>
  End of the cohort window. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="group_by" type="string">
  Dimension to group results by. Options: `campaign`, `creative`, `country`, `offer`, `paywall`. Default: `campaign`.
</ParamField>

<ParamField query="cohort_window_days" type="integer">
  Number of days to use for the payback window. Default: `30`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.flokit.ai/v1/reports/payback?start_date=2024-01-01&end_date=2024-03-31&group_by=campaign&cohort_window_days=30" \
  -H "Authorization: Bearer $FLOKIT_API_KEY"
```

### Response

```json theme={null}
{
  "data": [
    {
      "cohort": "US_iOS_Meta_BroadAudience_Jan",
      "spend": 48200.00,
      "cac": 12.40,
      "trials": 4200,
      "trial_conversion_rate": 0.71,
      "subscriptions": 2982,
      "roas_30d": 1.84,
      "payback_days": 22,
      "ltv_projected": 68.50
    },
    {
      "cohort": "US_iOS_Google_SearchBrand_Jan",
      "spend": 22100.00,
      "cac": 9.20,
      "trials": 2540,
      "trial_conversion_rate": 0.83,
      "subscriptions": 1989,
      "roas_30d": 2.31,
      "payback_days": 16,
      "ltv_projected": 79.10
    },
    {
      "cohort": "UK_Android_TikTok_CreativeTest_Feb",
      "spend": 11800.00,
      "cac": 18.70,
      "trials": 680,
      "trial_conversion_rate": 0.52,
      "subscriptions": 328,
      "roas_30d": 0.91,
      "payback_days": null,
      "ltv_projected": 41.20
    }
  ],
  "meta": {
    "currency": "USD",
    "generated_at": "2024-04-01T06:00:00Z",
    "cohort_window_days": 30
  }
}
```

`payback_days` is `null` when the cohort has not yet reached payback within the observation window.

***

## GET /v1/reports/cohorts

Returns cohort retention curves and LTV progression by week.

### Query parameters

<ParamField query="cohort_start" type="string" required>
  Start date for cohort selection. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="cohort_end" type="string" required>
  End date for cohort selection. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="group_by" type="string">
  Dimension to group cohorts by. Options: `campaign`, `creative`, `country`, `offer`, `paywall`. Default: `campaign`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.flokit.ai/v1/reports/cohorts?cohort_start=2024-01-01&cohort_end=2024-01-31&group_by=campaign" \
  -H "Authorization: Bearer $FLOKIT_API_KEY"
```

### Response

```json theme={null}
{
  "cohorts": [
    {
      "label": "US_iOS_Meta_BroadAudience_Jan",
      "weeks": [
        { "week": 1, "retained_pct": 0.91, "cumulative_revenue": 8.20 },
        { "week": 2, "retained_pct": 0.84, "cumulative_revenue": 14.80 },
        { "week": 4, "retained_pct": 0.76, "cumulative_revenue": 22.10 },
        { "week": 8, "retained_pct": 0.69, "cumulative_revenue": 38.50 },
        { "week": 13, "retained_pct": 0.61, "cumulative_revenue": 54.20 }
      ]
    },
    {
      "label": "US_iOS_Google_SearchBrand_Jan",
      "weeks": [
        { "week": 1, "retained_pct": 0.94, "cumulative_revenue": 9.40 },
        { "week": 2, "retained_pct": 0.89, "cumulative_revenue": 17.20 },
        { "week": 4, "retained_pct": 0.82, "cumulative_revenue": 26.80 },
        { "week": 8, "retained_pct": 0.77, "cumulative_revenue": 46.10 },
        { "week": 13, "retained_pct": 0.71, "cumulative_revenue": 65.30 }
      ]
    }
  ]
}
```