Access: System, Admin, and ClientAdmin users only.

The endpoint returns aggregate counts only. It never exposes employee IDs, names, SSNs, emails, addresses, total fields, or an Unclassified bucket. Legislative split is fixed per person from ClientEmployee.LegislativeID and is never derived from BaseEmployment.

Active counts use the BaseEmployment row whose effective interval contains periodEnd. Started and Terminated counts use the latest BaseEmployment row overlapping the period and the previous row of the same person. Started fires when that anchor starts in the period and the previous row is Inactive/Terminated or absent. Terminated fires when that same anchor is Terminated, starts in the period, and the previous row is active-classified. A termination followed by a rehire inside the same period therefore counts as Started, not Terminated, because the rehire row is the latest overlapping anchor.

Multi-value filters accept comma-separated values, pipe-separated values, repeated query keys, or mixed forms equivalently. Values inside one filter are OR-ed; different filters are AND-ed. Empty supplied filters apply no constraint. workLocationIds values less than or equal to zero select works-from-home rows. The optional groupBy query parameter is a strict single-value enum with supported values status, country, position, type, and workLocation. Filtering always narrows the anchor-row subset before grouping; grouping never bypasses active filters. The endpoint does not bind a statuses query parameter; caller-supplied statuses keys are ignored by the ASP.NET Core query binder.

When groupBy is omitted, no grouping fields are serialized and the response shape is unchanged. When it is supplied, each data point emits observed positive-count groups[] only, in deterministic key order: status/country/type by string, position by integer, and work-location with the works-from-home key first followed by ascending work-location IDs. Each group carries the full legislative split for Active, Started, and Terminated metrics. The six data-point-level scalar counts remain in the JSON payload but are set to 0; the per-group counts are authoritative. Group keys are non-PII and shaped as status string, country string, position integer, employee-type string, or {workLocationId, isWorkFromHome}. Status grouping uses broad EEStatus_v10 member names, excludes unmappable/Unknown statuses, and applies independently to each metric's own anchor row. The total emitted group count across all data points is capped at 5,000.

Weekly and bi-weekly periods use the caller role's existing week rules via CurrentRole.GetWeekOfYearInfo(date); Global employee roles observe Monday-based periods, while other roles observe Sunday-based periods. Bi-weekly periods are a continuous 14-day grid derived from the role-specific 2020 reference anchor and do not reset at year boundaries. Requests producing more than 500 data points return 400 Bad Request; data points are never truncated and granularity is never silently coarsened.

Per-field validation uses machine-readable error codes INVALID_DATE_RANGE, INVALID_COUNTRY_CODE, INVALID_POSITIVE_ID, and INVALID_ENUM_VALUE with apiResult.Code = "data_validation_error". Range-cap violations, including the 5,000 total-group cap, use BadRequest(message) and apiResult.Code = "400"; company-not-found uses NotFound(message) and apiResult.Code = "404"; unexpected failures use InternalServerError(message) and apiResult.Code = "500". No endpoint-specific error-code prefix is introduced.