Insights API

All endpoints require view:insights permission (executive, head, manager).

All endpoints accept these query params:

from_date — ISO date (default: 1 year ago)
to_date — ISO date (default: today)
location — filter by location name
gender — filter by gender value

Overview

`GET /api/insights/overview`

Returns all KPI summaries in a single call.

Response:

{
  "headcount": {
    "total": 25,
    "growth": 3,
    "starters": 5,
    "leavers": 2
  },
  "retention": {
    "turnover_rate": 0.08,
    "avg_tenure_months": 18
  },
  "diversity": {
    "gender": { "male": 12, "female": 10, "not_stated": 3 },
    "avg_age": 32
  },
  "compensation": {
    "median_salary": 85000,
    "min_salary": 55000,
    "max_salary": 140000
  },
  "structure": {
    "avg_span": 5.2,
    "largest_team": 12,
    "smallest_team": 2,
    "emp_to_mgr_ratio": "5:1"
  },
  "location": {
    "breakdown": [
      { "name": "Fitzroy", "count": 15 },
      { "name": "Remote", "count": 10 }
    ]
  }
}

Headcount

`GET /api/insights/headcount`

Monthly time series of headcount, starters, and leavers.

Response:

{
  "series": [
    { "label": "Mar 2025", "headcount": 22, "starters": 1, "leavers": 0 },
    { "label": "Apr 2025", "headcount": 23, "starters": 2, "leavers": 1 }
  ]
}

Retention

`GET /api/insights/retention`

Tenure distribution and turnover rate over time.

Response:

{
  "tenure_distribution": [
    { "bucket": "0-6 months", "count": 5 },
    { "bucket": "6-12 months", "count": 3 }
  ],
  "turnover_series": [
    { "label": "Mar 2025", "turnover_rate": 4.5, "leavers": 1, "headcount": 22 }
  ]
}

Diversity

`GET /api/insights/diversity`

Gender breakdown, manager gender, and age distribution.

Response:

{
  "gender": [
    { "gender": "male", "count": 12 },
    { "gender": "female", "count": 10 }
  ],
  "manager_gender": [
    { "gender": "male", "count": 3 },
    { "gender": "female", "count": 2 }
  ],
  "age_distribution": [
    { "bucket": "20-29", "count": 8 },
    { "bucket": "30-39", "count": 10 }
  ]
}

Compensation

`GET /api/insights/compensation`

Salary statistics, band distribution, and employment basis.

Response:

{
  "median_salary": 85000,
  "min_salary": 55000,
  "max_salary": 140000,
  "salary_bands": [
    { "band": "$60k-$80k", "count": 5 },
    { "band": "$80k-$100k", "count": 8 }
  ],
  "employment_basis": [
    { "basis": "full_time", "count": 20 },
    { "basis": "contractor", "count": 3 }
  ]
}

Structure

`GET /api/insights/structure`

Span of control and team size data.

Response:

{
  "avg_span": 5.2,
  "span_distribution": [
    { "bucket": "1-3", "count": 2 },
    { "bucket": "4-6", "count": 3 }
  ],
  "team_sizes": [
    { "squad_name": "Engineering", "size": 8 },
    { "squad_name": "Design", "size": 4 }
  ],
  "managers": [
    { "manager_name": "Jane Doe", "reports": 8 }
  ]
}

Location

`GET /api/insights/location`

Location breakdown with percentages.

Response:

{
  "breakdown": [
    { "name": "Fitzroy", "count": 15, "percentage": 60 },
    { "name": "Remote", "count": 10, "percentage": 40 }
  ],
  "total": 25
}