---
title: "Cohort retention grid"
method: GET
path: "/cohorts/grid"
tags: ["Cohort Analysis"]
---

# Cohort retention grid

`GET /cohorts/grid`

The retention grid for one shop: creators grouped by the month they first posted (rows), tracked across month-offsets M0..M6 (columns). Each cell carries raw counts — ``posted`` (creators who posted), ``gmv_count`` (creators who drove GMV) and ``total_videos`` — so a consumer derives % Posting / % Driving GMV / videos-per-creator itself. Omit ``product_id`` for the latest all-products snapshot, or pass one to live-aggregate that product's cohorts. Single-shop only.

## Query parameters

- `product_id` string, nullable — Optional product filter; omit for the all-products grid.

## Response `200`

Successful Response

- CohortGridResponse — Full cohort grid for one shop (optionally re-anchored to one product).
  - `shop_id` integer, required
  - `product_id` string, nullable — Product filter, or null for the all-products grid.
  - `computed_date` string, date, nullable — Snapshot date for the default (no-product) grid; null for the live product-filtered path.
  - `offsets` integer[] — Month offsets the grid tracks (M0..M6).
  - `cohorts` CohortRow[]
    - `cohort_month` string, date, required — First-video month for this cohort.
    - `affiliates` integer — Cohort size (the denominator for % metrics).
    - `cells` CohortCell[] — Triangle of populated month-offset cells.
      - `offset` integer, required — Months since cohort start (M0..M6).
      - `posted` integer — Distinct creators who posted ≥1 video in this offset month.
      - `gmv_count` integer — Distinct creators who drove GMV in this offset month.
      - `total_videos` integer — Total videos posted by the cohort in this offset month.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)