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

# Builder user cohort composition

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

Cohort composition of the builder's attributed users over the period, split by all-time profitability tier (pnlTiers) and size tier (sizeTiers), with per-cohort users, share of total, builder fees, volume, realized PnL, and fills. Wallets missing from the traders rollup appear under tier 'untracked' so per-tier user counts always sum to totalUsers. Tiers are lifetime labels — the pulse cohort endpoints use 30d-rolling tiers, so the same wallet can sit in a different cohort there.

## Path parameters

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

## Query parameters

- `period` 'day' | 'week' | 'month'

## Response `200`

OK

- BuilderCohortsBody
  - `$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
  - `dataNotes` string, required
  - `period` string, required
  - `pnlTiers` BuilderCohortRow[], nullable, required — Composition by profitability tier, largest cohort first
    - `builderFeesUsd` number, double, required — Builder fees this cohort paid in the period
    - `fills` integer, required
    - `pnl` number, double, required — Realized PnL on this cohort's attributed fills in the period
    - `share` number, double, required — users / totalUsers; 0 when the builder had no attributed users
    - `tier` string, required — All-time cohort tier label (money_printer..giga_rekt / leviathan..shrimp) or 'untracked'. Lifetime classification from the traders rollup — the pulse cohort endpoints use 30d-rolling tiers, so the same wallet can sit in a different cohort there; the period-scoped aggregates below are attributed to these lifetime labels
    - `users` integer, required — Distinct attributed wallets in this tier over the period
    - `volumeUsd` number, double, required — Attributed fill volume of this cohort in the period
  - `sizeTiers` BuilderCohortRow[], nullable, required — Composition by size tier, largest cohort first
    - `builderFeesUsd` number, double, required — Builder fees this cohort paid in the period
    - `fills` integer, required
    - `pnl` number, double, required — Realized PnL on this cohort's attributed fills in the period
    - `share` number, double, required — users / totalUsers; 0 when the builder had no attributed users
    - `tier` string, required — All-time cohort tier label (money_printer..giga_rekt / leviathan..shrimp) or 'untracked'. Lifetime classification from the traders rollup — the pulse cohort endpoints use 30d-rolling tiers, so the same wallet can sit in a different cohort there; the period-scoped aggregates below are attributed to these lifetime labels
    - `users` integer, required — Distinct attributed wallets in this tier over the period
    - `volumeUsd` number, double, required — Attributed fill volume of this cohort in the period
  - `totalUsers` integer, required — Distinct wallets with attributed fills in the period
  - `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)