---
title: "Builder retention cohorts"
method: GET
path: "/api/public/v1/builders/{builder}/retention"
tags: ["Builder Analytics"]
---

# Builder retention cohorts

`GET /api/public/v1/builders/{builder}/retention`

Retention matrix for the builder's users, computed on the orders plane: wallets are cohorted by the calendar month (or ISO week, with granularity=weekly) of their first builder-fee order via this builder, and 'active in month M' means they placed at least one builder-fee order that month (the order need not fill, so counts can exceed the attributed-fill user counts on the cohorts and overlap endpoints). Oldest cohort first; each cohort's activeWallets series starts at its own period (index 0 == newWallets). revenueWeighted=true adds a parallel activeRevenueUsd fee series; covers the last 12 months or 16 weeks depending on granularity.

## Path parameters

- `builder` string, required — Builder address (0x-hex)

## Query parameters

- `granularity` 'monthly' | 'weekly'
- `revenueWeighted` boolean — Add the attributed-fee series per cohort (fill plane)

## Response `200`

OK

- BuilderRetentionBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `builder` string, required
  - `builderName` string — Known display name for the builder; omitted if unknown
  - `cohorts` BuilderRetentionCohort[], nullable, required — Oldest cohort first; capped at the last 12 calendar months (monthly) or 16 ISO weeks (weekly)
    - `activeRevenueUsd` number[], nullable — Only when revenueWeighted=true: join-attributed builder fees this cohort's wallets paid per period, parallel to activeWallets (index k = k periods after the cohort period). Fill plane — see dataNotes
    - `activeWallets` integer[], nullable, required — Of those, wallets active per subsequent period, where 'active' = placed at least one builder-fee order that calendar month (or that ISO week under weekly granularity; orders plane — the order need not fill, so these counts can exceed the attributed-fill user counts on the cohorts/overlap endpoints); index 0 = the cohort period itself (== newWallets), index k = k periods later, up to the current period (max 12 entries monthly, 16 weekly)
    - `month` string, required — Cohort period start (UTC) — the calendar month (YYYY-MM) under monthly granularity, or the ISO-week Monday (YYYY-MM-DD) under weekly. Wallets whose first order via this builder landed in that period
    - `newWallets` integer, required — Wallets first seen in this period (placed their first builder-fee order via this builder)
  - `dataNotes` string, required
  - `granularity` string, required — Cohort period length: 'monthly' (calendar months) or 'weekly' (ISO weeks)
  - `revenueWeighted` boolean, required — Whether the per-cohort activeRevenueUsd fee series is included
  - `verified` BuilderStamp
    - `coverage` BuilderCoverage, required
      - `attributed_fees_usd` number, double, required — Join-attributed fees in the rollup window
      - `computed_at` string, required — When the rollup was computed (RFC3339)
      - `ledger_fees_usd` number, double, required — Exact ledger revenue in the rollup window
      - `ratio` number, double, required — attributed_fees / ledger_fees — the share of revenue the fill-level metrics account for
      - `window_end` string, required — End of that window (RFC3339)
      - `window_start` string, required — Start of the window the coverage rollup was computed over (RFC3339)
    - `ledger_block` integer, required — Latest block in HL's builder-fee ledger this data was verified against
    - `ledger_chain_time` string, required — Chain timestamp of that ledger entry (RFC3339)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `504` — Gateway Timeout

---

[API](https://skmtc.dev/coinversa/apis/coinversa-api.md) · [All operations](https://skmtc.dev/coinversa/apis/coinversa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coinversa/coinversa-api/revisions/77c03c427063/schema)