> ## Documentation Index > Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Builder retention cohorts > Retention matrix for the builder's users: wallets are cohorted by the calendar month (or ISO week, with granularity=weekly) of their first activity via this builder, and each later period counts how many of that cohort were active again. WHICH PLANE defines 'first' and 'active' is disclosed per response in dataNotes: the attribution rollup's presence rows (at least one attributed fill that period) whenever it can serve the builder, otherwise the orders plane (at least one builder-fee order placed that period — the order need not fill, so those 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, cohorted identically to activeWallets; covers the last 12 months or 16 weeks depending on granularity. ## OpenAPI ````yaml /api-reference/openapi.json get /api/public/v1/builders/{builder}/retention openapi: 3.1.0 info: title: coinversa-api version: 0.1.0 servers: - url: https://api.coinversa.ai description: Production security: [] paths: /api/public/v1/builders/{builder}/retention: get: tags: - Builder Analytics summary: Builder retention cohorts description: >- Retention matrix for the builder's users: wallets are cohorted by the calendar month (or ISO week, with granularity=weekly) of their first activity via this builder, and each later period counts how many of that cohort were active again. WHICH PLANE defines 'first' and 'active' is disclosed per response in dataNotes: the attribution rollup's presence rows (at least one attributed fill that period) whenever it can serve the builder, otherwise the orders plane (at least one builder-fee order placed that period — the order need not fill, so those 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, cohorted identically to activeWallets; covers the last 12 months or 16 weeks depending on granularity. operationId: get-api-public-v1-builders-by-builder-retention parameters: - description: Builder address (0x-hex) in: path name: builder required: true schema: description: Builder address (0x-hex) type: string - explode: false in: query name: granularity schema: default: monthly enum: - monthly - weekly type: string - description: Add the attributed-fee series per cohort (fill plane) explode: false in: query name: revenueWeighted schema: default: false description: Add the attributed-fee series per cohort (fill plane) type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/BuilderRetentionBody' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unauthorized '422': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unprocessable Entity '429': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Too Many Requests '500': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Internal Server Error '504': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Gateway Timeout security: - apiKey: [] components: schemas: BuilderRetentionBody: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/BuilderRetentionBody.json format: uri readOnly: true type: string builder: type: string builderName: description: Known display name for the builder; omitted if unknown type: string cohorts: description: >- Oldest cohort first; capped at the last 12 calendar months (monthly) or 16 ISO weeks (weekly) items: $ref: '#/components/schemas/BuilderRetentionCohort' type: - array - 'null' dataNotes: type: string granularity: description: >- Cohort period length: 'monthly' (calendar months) or 'weekly' (ISO weeks) type: string revenueWeighted: description: Whether the per-cohort activeRevenueUsd fee series is included type: boolean verified: $ref: '#/components/schemas/BuilderStamp' required: - builder - granularity - revenueWeighted - cohorts - dataNotes type: object APIError: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/APIError.json format: uri readOnly: true type: string code: description: Machine-readable error code type: string current_tier: description: Caller's effective tier type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string required_tier: description: Minimum tier for this operation type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upgrade_url: description: Where to upgrade type: string type: object BuilderRetentionCohort: additionalProperties: false properties: activeRevenueUsd: description: >- 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 items: format: double type: number type: - array - 'null' activeWallets: description: >- 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) items: format: int32 type: integer type: - array - 'null' month: description: >- 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 type: string newWallets: description: >- Wallets first seen in this period (placed their first builder-fee order via this builder) format: int32 type: integer required: - month - newWallets - activeWallets type: object BuilderStamp: additionalProperties: false properties: coverage: $ref: '#/components/schemas/BuilderCoverage' description: >- Attribution coverage vs the ledger; null until the coverage pipeline is provisioned ledger_block: description: >- Latest block in HL's builder-fee ledger this data was verified against format: int64 type: integer ledger_chain_time: description: Chain timestamp of that ledger entry (RFC3339) type: string required: - ledger_block - ledger_chain_time - coverage type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object BuilderCoverage: additionalProperties: false properties: attributed_fees_usd: description: Join-attributed fees in the rollup window format: double type: number computed_at: description: When the rollup was computed (RFC3339) type: string ledger_fees_usd: description: Exact ledger revenue in the rollup window format: double type: number ratio: description: >- attributed_fees / ledger_fees — the share of revenue the fill-level metrics account for format: double type: number window_end: description: End of that window (RFC3339) type: string window_start: description: Start of the window the coverage rollup was computed over (RFC3339) type: string required: - window_start - window_end - ledger_fees_usd - attributed_fees_usd - ratio - computed_at type: object securitySchemes: apiKey: description: Get one at https://coinversa.ai/developers in: header name: X-API-Key type: apiKey ````