Reports API — Dashboard Stats and Summary Reports

The Reports API provides pre-aggregated analytics data drawn directly from the qr_codes and permissions tables. Both endpoints are available to all authenticated users regardless of role. The dashboard endpoint is designed for real-time widgets (no parameters, always reflects current state), while the summary endpoint supports arbitrary date-range filtering and groups data by operator and hour for deeper analysis.

GET /api/reports/dashboard

Returns a live snapshot of the system’s current state: QR code counts by status, permission totals and compliance breakdown, time averages, and the five most recently created permission records. All numeric values are returned as strings (PostgreSQL COUNT and ROUND output). Auth required: Bearer Query parameters: None Response 200

{
  "success": true,
  "data": {
    "qr": {
      "available": "15",
      "active": "3",
      "expired": "0",
      "disabled": "2",
      "total": "20"
    },
    "permissions": {
      "total_permissions": "142",
      "compliant": "118",
      "non_compliant": "21",
      "active_now": "3",
      "overdue": "1"
    },
    "averages": {
      "avg_time_used": "18.45",
      "avg_delay": "3.21",
      "avg_allowed": "20.00"
    },
    "recent_activity": [
      {
        "id": 142,
        "qr_id": 7,
        "received_by": "Juan Pérez",
        "allowed_minutes": 15,
        "exit_time": "2024-01-15T14:30:00.000Z",
        "return_time": "2024-01-15T14:48:00.000Z",
        "time_used_minutes": "18.00",
        "delay_minutes": "3.00",
        "is_compliant": false,
        "enabled_by_name": "Ana Torres"
      }
    ]
  }
}

Show data.qr fields

available

string

Number of QR codes currently in available status.

active

string

Number of QR codes currently in active status (pass is out).

expired

string

Number of QR codes in expired status.

disabled

string

Number of QR codes that have been manually disabled.

total

string

Total QR codes across all statuses.

Show data.permissions fields

total_permissions

string

All-time count of permission records.

compliant

string

Count of closed permissions where is_compliant = true.

non_compliant

string

Count of closed permissions where is_compliant = false.

active_now

string

Permissions with no return_time — i.e. passes currently out.

overdue

string

Subset of active_now where the bearer has already exceeded their time budget. Computed as:

return_time IS NULL AND exit_time < NOW() - INTERVAL '1 minute' * allowed_minutes

Show data.averages fields

avg_time_used

string | null

Average time_used_minutes across all closed permissions (2 decimal places). null if no closed permissions exist.

avg_delay

string | null

Average delay_minutes across all closed permissions (2 decimal places). null if none exist.

avg_allowed

string | null

Average allowed_minutes across all closed permissions (2 decimal places). null if none exist.

Show data.recent_activity fields

integer

Permission record ID.

qr_id

integer

ID of the associated QR code.

received_by

string | null

Name of the pass bearer.

allowed_minutes

integer

Original time budget.

exit_time

string | null

ISO 8601 timestamp when the pass was issued.

return_time

string | null

ISO 8601 timestamp of return. null if still active.

time_used_minutes

string | null

Total minutes used. null if still active.

delay_minutes

string | null

Minutes over budget. null if still active.

is_compliant

boolean | null

Compliance flag. null if still active.

enabled_by_name

string | null

Display name of the operator who issued the pass.

Understanding overdue: A permission is counted as overdue when return_time IS NULL (the bearer has not yet returned) and exit_time + allowed_minutes < NOW() (their deadline has already passed). These records represent active compliance violations that may need operator intervention.

curl http://localhost:4000/api/reports/dashboard \
  -H "Authorization: Bearer <token>"

GET /api/reports/summary

Returns aggregated compliance statistics for a configurable time window. Three result sets are always included: an overall numeric summary, a per-operator breakdown (top 10 by volume), and an hourly distribution of exits across the day. All values are strings from PostgreSQL aggregation functions. Auth required: Bearer

startDate

string

ISO 8601 date-time lower bound. Filters created_at >= startDate. Optional — omit for all-time data.

endDate

string

ISO 8601 date-time upper bound. Filters created_at <= endDate. Optional — omit for all-time data.

Response 200

{
  "success": true,
  "data": {
    "summary": {
      "total": "142",
      "compliant": "118",
      "non_compliant": "21",
      "avg_time": "18.45",
      "avg_delay": "3.21",
      "max_delay": "45.00"
    },
    "by_admin": [
      { "name": "Ana Torres", "total": "78", "compliant": "65" },
      { "name": "Carlos Ruiz", "total": "64", "compliant": "53" }
    ],
    "hourly_distribution": [
      { "hour": "9", "total": "22" },
      { "hour": "10", "total": "18" },
      { "hour": "14", "total": "31" }
    ]
  }
}

Show data.summary fields

total

string

Total permission records in the selected date range.

compliant

string

Count of records where is_compliant = true.

non_compliant

string

Count of records where is_compliant = false.

avg_time

string | null

Average time_used_minutes across all records in range (2 decimal places).

avg_delay

string | null

Average delay_minutes across all records in range (2 decimal places).

max_delay

string | null

Maximum single delay_minutes value in range (2 decimal places). Useful for identifying worst-case violations.

Show data.by_admin fields

name

string | null

Operator display name. null if the user record was deleted.

total

string

Total permissions enabled by this operator in the selected range.

compliant

string

Count of compliant permissions for this operator.

Show data.hourly_distribution fields

hour

string

Hour of day (0–23, extracted from exit_time).

total

string

Number of exits that started during this hour in the selected range.

curl "http://localhost:4000/api/reports/summary?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"

Combine startDate and endDate with your frontend’s date picker to power weekly or monthly compliance reports. The by_admin array returns up to 10 operators sorted by total volume descending — ideal for a leaderboard widget.

Active permissions (those with no return_time) are included in total counts but contribute null to time and delay averages, since AVG in PostgreSQL ignores NULL values. The compliant and non_compliant counts only reflect closed permissions where is_compliant has been computed.

Overview

Endpoints

Reports API — Dashboard Stats and Summary Reports

GET /api/reports/dashboard

GET /api/reports/summary

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/reports/dashboard

​GET /api/reports/summary

Build docs developers (and LLMs) love

GET /api/reports/dashboard

GET /api/reports/summary