Analytics, Dashboards & Reports REST API Reference

The analytics and reporting surface of the Workforce Intelligence OS is split into four layers: per-user employee dashboards, manager team views, admin org-wide health panels, and a dedicated analytics router for deeper performance signals. Every endpoint is protected by a valid JWT and enforces role or permission checks before returning data. All paths are prefixed with /api/v1.

All analytics endpoints require an Authorization: Bearer <token> header. Requests without a valid token receive 401 AUTH_ERROR.

Employee Dashboard

`GET /api/v1/dashboard/employee`

Returns KPI cards and live session state for the currently authenticated employee. Any active role may call this endpoint. Auth: Any authenticated user (get_current_user).

attendance

object

required

Current shift attendance summary.

Show AttendanceSummary fields

checked_in_today

boolean

Whether the user has checked in today.

check_in_at

string | null

ISO-8601 UTC timestamp of check-in.

check_out_at

string | null

ISO-8601 UTC timestamp of check-out.

work_mode

string | null

OFFICE or WFH.

session_status

string | null

Current session status enum value.

duration_minutes

integer | null

Total session duration so far in minutes.

tasks

object

required

Aggregated task counts for the user.

Show TaskCounts fields

total

integer

All assigned tasks.

in_progress

integer

Tasks currently in progress.

completed

integer

Completed tasks.

blocked

integer

Blocked tasks.

overdue

integer

Past due-date and not yet completed or reviewed.

timer

object

required

Active time-log state.

Show TimerState fields

active

boolean

Whether a timer is currently running.

task_id

string | null

UUID of the task being timed.

task_title

string | null

Title of the active task.

started_at

string | null

ISO-8601 UTC start timestamp.

elapsed_minutes

integer | null

Minutes elapsed since start.

attendance_status

string

Human-readable session status, e.g. "checked_in" or "not_checked_in".

total_time_today

integer

Total session minutes today.

productive_time_today

integer

Total logged productive minutes today.

tasks_in_progress

integer

Count of tasks currently in-progress.

tasks_due_soon

integer

Tasks due within 2 days.

Example Response

{
  "attendance": {
    "checked_in_today": true,
    "check_in_at": "2025-01-20T09:02:14Z",
    "check_out_at": null,
    "work_mode": "OFFICE",
    "session_status": "checked_in",
    "duration_minutes": 127
  },
  "tasks": {
    "total": 12,
    "in_progress": 3,
    "completed": 7,
    "blocked": 1,
    "overdue": 1
  },
  "timer": {
    "active": true,
    "task_id": "b3a1c2d4-...",
    "task_title": "Implement login flow",
    "started_at": "2025-01-20T10:15:00Z",
    "elapsed_minutes": 32
  },
  "attendance_status": "checked_in",
  "total_time_today": 127,
  "productive_time_today": 95,
  "tasks_in_progress": 3,
  "tasks_due_soon": 2
}

Manager Dashboard

`GET /api/v1/dashboard/manager`

Returns team attendance, pending approval counts, and overdue/blocked task summaries for the authenticated manager. Admins calling this endpoint see all active users as their “team.” Auth: MANAGER or ADMIN role required.

team_attendance_today

array

List of team member attendance records for today.

Show TeamMemberAttendance fields

user_id

string

UUID of the team member.

full_name

string

Display name.

checked_in

boolean

Whether they have an active session.

work_mode

string | null

OFFICE or WFH.

check_in_at

string | null

ISO-8601 UTC check-in time.

pending_approvals_count

integer

Total pending leave requests + attendance corrections awaiting this manager.

overdue_tasks_count

integer

Overdue tasks across the team.

blocked_tasks_count

integer

Blocked tasks across the team.

team_members_active

integer

Number of team members currently checked in.

Admin Dashboard

`GET /api/v1/dashboard/admin`

Returns organisation-wide health metrics including headcount, attendance breakdown, open alerts, and project counts. Auth: ADMIN role required.

total_users

integer

Total registered users.

active_users

integer

Users with ACTIVE status.

checked_in_today

integer

Employees currently checked in.

wfh_today

integer

Employees working from home today.

office_today

integer

Employees in the office today.

pending_approvals_count

integer

Total org-wide pending approval decisions.

open_alerts_count

integer

Number of unresolved system alerts.

overdue_tasks_count

integer

Org-wide overdue task count.

active_projects

integer

Projects with ACTIVE or APPROVED status.

Example Response

{
  "total_users": 84,
  "active_users": 78,
  "checked_in_today": 51,
  "wfh_today": 14,
  "office_today": 37,
  "pending_approvals_count": 9,
  "open_alerts_count": 3,
  "overdue_tasks_count": 11,
  "active_projects": 6
}

Admin Analytics Dashboard

`GET /api/v1/dashboard/admin/analytics`

Delivers a rich analytics payload for the admin overview tab: KPIs, 7-day attendance trends, task and project statistics, per-department comparison, people exceptions, and recent activity. Auth: ADMIN role required.

kpis

object

Top-level key performance indicators.

Show AdminAnalyticsKPIs fields

total_employees

integer

total_projects

integer

pending_approvals

integer

attendance_rate

number

Floating-point percentage (0–100).

checked_in_today

integer

late_today

integer

wfh_today

integer

attendance_trend

array

Daily attendance data points (typically last 7 days).

Show AdminAnalyticsAttendanceTrend fields

date

string

ISO date string YYYY-MM-DD.

checked_in

integer

late

integer

absent

integer

task_statistics

object

Counts by status: total, completed, in_progress, on_hold, pending, rejected.

project_statistics

object

Counts by status: total, approved, pending, rejected, active.

department_comparison

array

Per-department attendance rate and task completion metrics.

people_exceptions

array

Employees flagged for exceptions (e.g. chronic late arrivals, blockers).

recent_activity

array

Latest system-wide activity log entries.

Use this endpoint to power a scrollable admin command-centre panel. Cache responses on the frontend for up to 60 seconds to reduce database load.

`GET /api/v1/dashboard/admin/users-analytics`

Returns the Users tab analytics payload: employee roster, role distribution, department distribution, attendance-by-department breakdowns, and individual performance metrics. Auth: ADMIN or HR_OPERATIONS role required.

business_date

string

The current business date in YYYY-MM-DD format (Asia/Karachi timezone).

timezone

string

Always "Asia/Karachi".

summary

object

High-level user counts.

Show UsersAnalyticsSummary fields

total_employees

integer

active_employees

integer

admins

integer

managers

integer

employees

integer

interns

integer

present_today

integer

late_today

integer

on_leave

integer

wfh_today

integer

new_users_this_month

integer

role_distribution

array

Label/count pairs per role.

department_distribution

array

Label/count pairs per department.

attendance_by_department

array

Per-department attendance rate, headcount, late count.

employee_roster

array

Full employee activity roster including attendance status, task counts, and logged hours.

employee_performance

array

Per-employee performance index, attendance rate, and risk flags.

`GET /api/v1/dashboard/admin/user-management-overview`

Alias for admin/users-analytics. Returns the same UsersAnalyticsDashboard payload — provided for frontend route compatibility. Auth: ADMIN or HR_OPERATIONS role required.

`GET /api/v1/dashboard/admin/communication-analytics`

Returns the Communication tab analytics payload: messaging activity, meeting summaries, announcement counts, and support ticket overviews. Auth: ADMIN or HR_OPERATIONS role required.

summary

object

Show CommunicationAnalyticsSummary fields

unread_messages

integer

active_conversations

integer

meetings_today

integer

upcoming_meetings

integer

announcements_this_week

integer

open_support_tickets

integer

messages_by_day

array

Daily message volume trend (date + count).

meetings_by_week

array

Weekly meeting counts as label/count pairs.

support_tickets_by_status

array

Ticket distribution by status.

recent_conversations

array

Latest active conversations with participant count and unread flag.

upcoming_meetings

array

Scheduled meetings starting soonest.

recent_announcements

array

Recently published announcements.

support_tickets

array

Recent open support ticket summaries.

`GET /api/v1/dashboard/admin/projects-tasks-analytics`

Returns the Projects & Tasks tab analytics payload: task status distribution, project progress, and detailed project/task tables. Auth: ADMIN or HR_OPERATIONS role required.

summary

object

Show ProjectsTasksSummary fields

total_projects

integer

active_projects

integer

completed_projects

integer

blocked_projects

integer

active_tasks

integer

overdue_tasks

integer

completed_tasks

integer

pending_tasks

integer

task_status_distribution

array

Label/count pairs per task status.

task_priority_distribution

array

Label/count pairs per task priority.

project_progress

array

Project completion percentage distribution.

tasks_by_department

array

Task counts per department.

projects

array

Project table rows with team size, status, and progress.

tasks

array

Task table rows with assignee, priority, status, and logged minutes.

Manager Analytics Tabs

`GET /api/v1/dashboard/manager/overview`

Returns the manager’s overview tab: KPIs, 7-day attendance trend, team health score, pending actions, and upcoming meetings. Auth: MANAGER or ADMIN role required.

kpis

object

Show ManagerOverviewKPIs fields

team_members

integer

present_today

integer

pending_approvals

integer

active_tasks

integer

overdue_tasks

integer

projects_in_progress

integer

eod_reports_pending

integer

team_workload

integer

attendance_trend

array

7-day team attendance trend (date, checked_in, late, absent).

team_health

object

Score (0–100), label, blocked/overdue counts, and active member count.

pending_actions

array

Prioritised list of actionable items with route hints.

recent_activity

array

Recent team activity log entries.

members_needing_attention

array

Team members flagged for exceptions.

upcoming_meetings

array

Team meetings starting soonest.

`GET /api/v1/dashboard/manager/team-analytics`

Returns the manager’s Team tab: per-member attendance, workload distribution, task completion metrics, and the employee roster and performance tables. Auth: MANAGER or ADMIN role required.

summary

object

Team headcount, checked-in count, late count, on-leave count, WFH count, and high-workload member count.

attendance_by_member

array

Per-member attendance label/count pairs.

workload_distribution

array

Task workload per team member.

task_completion_by_member

array

Completed-task counts per member.

logged_hours_trend

array

Daily logged-hours trend over the last 7 days.

employee_roster

array

Full activity roster for direct reports.

employee_performance

array

Per-member performance index and risk flags.

`GET /api/v1/dashboard/manager/approvals-analytics`

Returns the manager’s Approvals tab: pending leave requests, pending attendance corrections, and weekly approval throughput. Auth: MANAGER or ADMIN role required.

summary

object

Counts of pending leaves, WFH requests, attendance corrections, pending EODs, approvals this week, and rejections this week.

pending_leaves

array

Leave requests awaiting this manager’s decision.

pending_corrections

array

Attendance correction requests awaiting decision.

`GET /api/v1/dashboard/manager/projects-tasks-analytics`

Returns the manager’s Projects & Tasks tab, scoped to the manager’s direct reports. Auth: MANAGER or ADMIN role required. Returns the same ProjectsTasksAnalyticsDashboard schema as the admin version, filtered to the manager’s team scope.

`GET /api/v1/dashboard/manager/eod-reports-analytics`

Returns the manager’s EOD & Reports tab: EOD submission status, productivity trend, and per-member report rows. Auth: MANAGER or ADMIN role required.

summary

object

Show ManagerEodSummary fields

submitted_today

integer

pending_reviews

integer

average_productivity

number

blockers_reported

integer

team_logged_hours

number

missing_eods

integer

reports

array

Per-member EOD report rows including attendance status, logged hours, and review status.

productivity_trend

array

Daily productivity score distribution.

blocker_trend

array

Daily blocker count trend.

Analytics Signals

`GET /api/v1/analytics/best-performers`

Returns a ranked list of top-performing employees based on task completion and attendance consistency. Requires analytics.view_org permission. Auth: analytics.view_org permission required.

[]

array

Array of BestPerformer objects.

Show BestPerformer fields

user_id

string

UUID of the employee.

full_name

string

score

number

Composite performance score.

completed_tasks

integer

Count of completed tasks in the scoring window.

attendance_consistency

number

Attendance consistency score (0–1).

`GET /api/v1/analytics/workload-balance`

Returns per-employee workload distribution and overload flags. Accessible to users with analytics.view_org or analytics.view_team. Auth: analytics.view_org or analytics.view_team permission required.

[]

array

Array of WorkloadBalance objects.

Show WorkloadBalance fields

user_id

string

UUID of the employee.

full_name

string

active_tasks

integer

Number of currently active tasks assigned.

overloaded

boolean

Whether the employee exceeds the workload threshold.

`GET /api/v1/analytics/burnout-risks`

Returns employees exhibiting burnout risk signals based on consecutive high-hour working days. Requires analytics.view_org permission. Auth: analytics.view_org permission required.

[]

array

Array of BurnoutRisk objects.

Show BurnoutRisk fields

user_id

string

UUID of the employee.

full_name

string

consecutive_high_hour_days

integer

Days in a row with above-threshold logged hours.

risk_level

string

One of Low, Medium, High.

This endpoint only returns employees flagged above the low-risk threshold. Employees with no risk signals are omitted from the response.

`GET /api/v1/analytics/productivity-trend/{user_id}`

Returns a time-series of daily productivity scores for a specific user. The authenticated user may always view their own trend; managers and admins may view any user in their scope. Auth: Any authenticated user. Caller must have view access to the target user.

user_id

string

required

UUID of the employee whose trend to fetch.

[]

array

Array of ProductivityTrend objects.

Show ProductivityTrend fields

date

string

ISO date string YYYY-MM-DD.

score

number

Productivity score for that day.

Example Response

[
  { "date": "2025-01-14", "score": 82.5 },
  { "date": "2025-01-15", "score": 91.0 },
  { "date": "2025-01-16", "score": 74.3 }
]

Reports

`GET /api/v1/reports/employee`

Returns the authenticated user’s personal performance report for a specified date range. Auth: Any authenticated user.

start_date

string

required

Report start date — ISO format YYYY-MM-DD.

end_date

string

required

Report end date — ISO format YYYY-MM-DD.

user_id

string

UUID of the employee.

full_name

string

attendance_days

integer

Days with a completed attendance session.

late_days

integer

wfh_days

integer

total_logged_hours

number

`GET /api/v1/reports/manager`

Returns performance reports for all team members scoped to the authenticated manager’s direct reports. Admins see the full organisation. Auth: MANAGER, HR_OPERATIONS, or ADMIN role required.

start_date

string

required

Report start date — ISO format YYYY-MM-DD.

end_date

string

required

Report end date — ISO format YYYY-MM-DD.

[]

array

Array of WeeklyReportRead objects — one per scoped team member.

`GET /api/v1/reports/hr`

Returns performance report aggregations for all employees in the organisation, scoped to HR. Auth: HR_OPERATIONS or ADMIN role required.

start_date

string

required

ISO format YYYY-MM-DD.

end_date

string

required

ISO format YYYY-MM-DD.

[]

array

Array of WeeklyReportRead objects for the full org.

`GET /api/v1/reports/admin`

Returns organisation-wide performance report data for the admin. Identical in structure to the HR report but restricted to ADMIN role. Auth: ADMIN role required.

start_date

string

required

ISO format YYYY-MM-DD.

end_date

string

required

ISO format YYYY-MM-DD.

`GET /api/v1/reports/team-performance`

Returns a paginated, filterable team performance report. Supports date range anchoring via a period mode or explicit start_date/end_date. Auth: MANAGER, HR_OPERATIONS, or ADMIN role required.

period

string

One of daily, weekly, monthly, or custom. Defaults to weekly.

date

string

Anchor date for daily/weekly/monthly periods. ISO format YYYY-MM-DD.

start_date

string

Explicit start date for custom period. ISO format YYYY-MM-DD.

end_date

string

Explicit end date for custom period. ISO format YYYY-MM-DD.

string

Filter by employee name, email, role, department, or designation.

department_id

string

Filter by department UUID.

role

string

Filter by role string.

page

integer

Page number (1-based). Omit for unpaginated results.

page_size

integer

Rows per page. Min 1, max 200.

start_date

string

Effective start date of the report period.

end_date

string

Effective end date of the report period.

rows

array

Per-employee rows with hours, task counts, attendance breakdowns, and EOD status.

Example Request

GET /api/v1/reports/team-performance?period=weekly&date=2025-01-20&page=1&page_size=25
Authorization: Bearer <token>

`GET /api/v1/reports/team-performance/export`

Streams the team performance report as a CSV file. Accepts the same filter parameters as team-performance but returns all rows (no pagination). The response has Content-Type: text/csv and a Content-Disposition: attachment header. Auth: MANAGER, HR_OPERATIONS, or ADMIN role required.

period

string

One of daily, weekly, monthly, custom. Defaults to weekly.

date

string

Anchor date ISO YYYY-MM-DD.

start_date

string

Explicit start date for custom period.

end_date

string

Explicit end date for custom period.

string

Name/email/role filter.

department_id

string

Filter by department UUID.

role

string

Filter by role string.

The exported CSV includes columns: Employee Name, Email, Role, Department, Designation, Hours, Tasks Worked On, Completed Tasks, Late, Early, WFH, Absences, EOD Status, Date Range.

Example Request

GET /api/v1/reports/team-performance/export?period=weekly&date=2025-01-20
Authorization: Bearer <token>

Error Responses

All analytics and reports endpoints share the standard error envelope:

{
  "error": {
    "code": "PERMISSION_ERROR",
    "message": "Admin only",
    "details": []
  }
}

HTTP Status	Code	Reason
`401`	`AUTH_ERROR`	Missing or invalid JWT
`403`	`PERMISSION_ERROR`	Insufficient role or permission
`422`	`VALIDATION_ERROR`	Invalid date range or query parameters
`500`	`INTERNAL_ERROR`	Service computation failure

Overview

Endpoints

Employee Dashboard

`GET /api/v1/dashboard/employee`

Manager Dashboard

`GET /api/v1/dashboard/manager`

Admin Dashboard

`GET /api/v1/dashboard/admin`

Admin Analytics Dashboard

`GET /api/v1/dashboard/admin/analytics`

`GET /api/v1/dashboard/admin/users-analytics`

`GET /api/v1/dashboard/admin/user-management-overview`

`GET /api/v1/dashboard/admin/communication-analytics`

`GET /api/v1/dashboard/admin/projects-tasks-analytics`

Manager Analytics Tabs

`GET /api/v1/dashboard/manager/overview`

`GET /api/v1/dashboard/manager/team-analytics`

`GET /api/v1/dashboard/manager/approvals-analytics`

`GET /api/v1/dashboard/manager/projects-tasks-analytics`

`GET /api/v1/dashboard/manager/eod-reports-analytics`

Analytics Signals

`GET /api/v1/analytics/best-performers`

`GET /api/v1/analytics/workload-balance`

`GET /api/v1/analytics/burnout-risks`

`GET /api/v1/analytics/productivity-trend/{user_id}`

Reports

`GET /api/v1/reports/employee`

`GET /api/v1/reports/manager`

`GET /api/v1/reports/hr`

`GET /api/v1/reports/admin`

`GET /api/v1/reports/team-performance`

`GET /api/v1/reports/team-performance/export`

Error Responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Employee Dashboard

​GET /api/v1/dashboard/employee

​Manager Dashboard

​GET /api/v1/dashboard/manager

​Admin Dashboard

​GET /api/v1/dashboard/admin

​Admin Analytics Dashboard

​GET /api/v1/dashboard/admin/analytics

​GET /api/v1/dashboard/admin/users-analytics

​GET /api/v1/dashboard/admin/user-management-overview

​GET /api/v1/dashboard/admin/communication-analytics

​GET /api/v1/dashboard/admin/projects-tasks-analytics

​Manager Analytics Tabs

​GET /api/v1/dashboard/manager/overview

​GET /api/v1/dashboard/manager/team-analytics

​GET /api/v1/dashboard/manager/approvals-analytics

​GET /api/v1/dashboard/manager/projects-tasks-analytics

​GET /api/v1/dashboard/manager/eod-reports-analytics

​Analytics Signals

​GET /api/v1/analytics/best-performers

​GET /api/v1/analytics/workload-balance

​GET /api/v1/analytics/burnout-risks

​GET /api/v1/analytics/productivity-trend/{user_id}

​Reports

​GET /api/v1/reports/employee

​GET /api/v1/reports/manager

​GET /api/v1/reports/hr

​GET /api/v1/reports/admin

​GET /api/v1/reports/team-performance

​GET /api/v1/reports/team-performance/export

​Error Responses

Build docs developers (and LLMs) love

Employee Dashboard

`GET /api/v1/dashboard/employee`

Manager Dashboard

`GET /api/v1/dashboard/manager`

Admin Dashboard

`GET /api/v1/dashboard/admin`

Admin Analytics Dashboard

`GET /api/v1/dashboard/admin/analytics`

`GET /api/v1/dashboard/admin/users-analytics`

`GET /api/v1/dashboard/admin/user-management-overview`

`GET /api/v1/dashboard/admin/communication-analytics`

`GET /api/v1/dashboard/admin/projects-tasks-analytics`

Manager Analytics Tabs

`GET /api/v1/dashboard/manager/overview`

`GET /api/v1/dashboard/manager/team-analytics`

`GET /api/v1/dashboard/manager/approvals-analytics`

`GET /api/v1/dashboard/manager/projects-tasks-analytics`

`GET /api/v1/dashboard/manager/eod-reports-analytics`

Analytics Signals

`GET /api/v1/analytics/best-performers`

`GET /api/v1/analytics/workload-balance`

`GET /api/v1/analytics/burnout-risks`

`GET /api/v1/analytics/productivity-trend/{user_id}`

Reports

`GET /api/v1/reports/employee`

`GET /api/v1/reports/manager`

`GET /api/v1/reports/hr`

`GET /api/v1/reports/admin`

`GET /api/v1/reports/team-performance`

`GET /api/v1/reports/team-performance/export`

Error Responses