# User statistics API reference Source: https://docs.settlemint.com/docs/api-reference/reference/user-statistics Read organization user statistics through the DALP Platform API, including total members, recently active members, and a cumulative member growth series for dashboards. An operator building an admin dashboard needs three plain numbers about the people in their organization: the total member count, how many were active recently, and how that membership grew over time. The user statistics API answers each one. These endpoints report member counts and growth for your authenticated organization, as a current total, a recent-activity count, and a daily cumulative series for charts. Every endpoint here is read-only. They report state the platform already holds. They do not create, invite, or remove members, and they do not change any account. For authentication and base URL setup, see [Getting started](/docs/api-reference/reference/getting-started). ## Scope [#scope] All three endpoints are scoped to the authenticated **organization**. "Users" means the members that belong to that organization: each result counts and charts the organization's own membership, never users from another organization. The active organization context bounds every read, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope). The counts are membership counts. A member is a person attached to the organization, regardless of how many wallets or assets they hold. If a request arrives without a resolved organization, the endpoints return zeros and empty series rather than an error, so a dashboard can render an empty state without special-casing the response. ## Endpoints [#endpoints] The user statistics API exposes three read endpoints: | Endpoint | Use it for | | --------------------------------- | -------------------------------------------------------------------------- | | `GET /api/v2/user-metrics` | The full set: total members, recently active members, and a growth series. | | `GET /api/v2/user-count-metrics` | The counts only: total members and recently active members. | | `GET /api/v2/user-growth-metrics` | The cumulative member growth series for charting. | All three endpoints return a JSON:API single-resource envelope with `data` and `links.self`. ## The time range [#the-time-range] Each endpoint accepts one optional query parameter, `timeRange`, an integer number of days between `1` and `365`. The default differs by endpoint, and the table below shows what the window controls in each response. | Endpoint | `timeRange` default | What it controls | | --------------------------------- | ------------------- | -------------------------------------------------------- | | `GET /api/v2/user-metrics` | `7` | The recent-activity window and the growth series length. | | `GET /api/v2/user-count-metrics` | `7` | The recent-activity window. | | `GET /api/v2/user-growth-metrics` | `30` | The growth series length. | The recent-activity window counts members whose most recent sign-in falls inside the last `timeRange` days. For a member who has never signed in, the platform uses the date the member joined the organization. The growth series runs daily from the start of the window to now. ## Query the full metrics set [#query-the-full-metrics-set] Use the metrics endpoint when a dashboard panel needs the headline counts and the growth chart in one call. ```bash curl --request GET \ "$DALP_API_URL/api/v2/user-metrics?timeRange=30" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": { "totalUsers": 128, "recentUsers": 42, "userGrowth": [ { "timestamp": "2026-05-23T00:00:00.000Z", "users": 110 }, { "timestamp": "2026-05-24T00:00:00.000Z", "users": 113 }, { "timestamp": "2026-06-22T00:00:00.000Z", "users": 128 } ], "timeRangeDays": 30 }, "links": { "self": "/v2/user-metrics" } } ``` The fields are: * `totalUsers`: every member in the organization, regardless of the time range. * `recentUsers`: members active inside the `timeRange` window. * `userGrowth`: the cumulative member count per day across the window. Each point's `users` value is the running total of members up to and including that day, so the series only rises or holds flat. * `timeRangeDays`: the time range the response used, echoed back so a caller can confirm the applied window. ## Query the counts only [#query-the-counts-only] Use the count endpoint when a panel needs the two headline numbers without the chart series. ```bash curl --request GET \ "$DALP_API_URL/api/v2/user-count-metrics?timeRange=30" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": { "totalUsers": 128, "recentUsers": 42, "timeRangeDays": 30 }, "links": { "self": "/v2/user-count-metrics" } } ``` `totalUsers` and `recentUsers` carry the same meaning as in the full metrics set. This endpoint omits the growth series, so the count endpoint is the lighter call when a tile shows only the current totals. ## Query the growth series [#query-the-growth-series] Use the growth endpoint when a chart needs only the cumulative series. ```bash curl --request GET \ "$DALP_API_URL/api/v2/user-growth-metrics?timeRange=90" \ --header "X-Api-Key: $DALP_API_TOKEN" ``` ```json { "data": { "userGrowth": [ { "timestamp": "2026-03-24T00:00:00.000Z", "users": 88 }, { "timestamp": "2026-03-25T00:00:00.000Z", "users": 90 }, { "timestamp": "2026-06-22T00:00:00.000Z", "users": 128 } ], "timeRangeDays": 90 }, "links": { "self": "/v2/user-growth-metrics" } } ``` Each point reports the cumulative member count at the end of that day. The first point already includes every member who joined before the window opened, so the line starts at the organization's running total rather than at zero. When the organization has no members yet, `userGrowth` is an empty array. ## Reading the growth series correctly [#reading-the-growth-series-correctly] The growth series is cumulative, not per-day additions. To show how many members joined on a given day, subtract the previous point's `users` value from the current one. The series is daily: each `timestamp` is the start of a day in UTC, and the final point reflects the total as of the request time. Because the series accumulates from a pre-window baseline, do not read the first point as "members who joined on the first day". The first point is the organization's total membership at the start of the requested window. ## Related [#related] * [Participant activity](/docs/api-reference/reference/participant-activity) for the on-chain event history of a participant's wallets, rather than organization membership counts. * [System value and transaction stats](/docs/api-reference/reference/system-value-and-transaction-stats) for the organization's total asset value and transfer activity. * [Organization and system scope](/docs/api-reference/reference/organization-system-scope) * [Getting started with API integration](/docs/api-reference/reference/getting-started)