Periodic Meeting Cost Reports and CSV Data Exports

The reports endpoints surface periodic meeting-cost summaries — spend totals, recurring series run-rates, trend comparisons, and the “reduced before send” metric. The scope of what each caller sees is determined entirely by their role: there is no request parameter that widens it, and participants are blocked entirely. Both the JSON view and the CSV export are written to the audit log on every access.

Role-to-scope mapping

Role	Report scope
`participant`	`403 Forbidden` — reports are not available
`organiser`	Meetings the caller organised (`own_meetings`)
`team_lead`	Meetings organised by their team (`own_team`)
`finance`	Org-wide
`admin`	Org-wide

Scope is derived server-side from the caller’s role and team assignment. There is no scope request parameter — a caller cannot widen their own scope. A team_lead assigned to team_id=eng will always see only that team’s meetings.

GET /api/v1/reports

Returns a digest for the most recent complete period (weekly or monthly). Callers with the organiser role see only their own meetings; team_lead callers see their team’s data; finance and admin see org-wide data. Participants receive 403. Both JSON and CSV responses are recorded in the audit log on every access.

Query parameters

string

default:"weekly"

The reporting period. Must be weekly or monthly.

string

An ISO 8601 date (YYYY-MM-DD). When provided, the report covers the complete period before this date rather than the most recent complete period. Use this to retrieve historical periods.

GET /api/v1/reports?period=monthly&anchor=2026-09-01
# Returns the completed monthly period before September 1st — i.e. August.

Response body

string

The period label, e.g. "2026-W35" or "2026-08".

string

ISO 8601 date of the first day of the period.

string

ISO 8601 date of the last day of the period.

string

The scope actually applied to this report ("own_meetings", "own_team", or "org_wide"), derived from the caller’s role.

string

ISO 4217 currency code for all monetary figures in this response.

string

Total payroll cost of all meetings in the period, as a decimal string.

integer

Number of completed meetings in the period.

number

Aggregate person-hours (sum of attendees × duration_hours for all meetings).

string | null

Total spend for the equivalent prior period. null if no data exists for that period.

number | null

Percentage change from previous_total to total_spend. Positive = increase. null if previous_total is unavailable.

array

Spend broken down by team, for org-wide scoped reports.

Show by_team item fields

string | null

Team identifier.

string | null

Display name of the team.

integer

Number of meetings for this team.

string

Total spend, as a decimal string.

array

Spend broken down by recurring meeting series.

Show by_series item fields

string | null

Provider series identifier.

string | null

Series title.

integer

Number of occurrences in the period.

string

Total spend across all occurrences, as a decimal string.

string | null

Annual run-rate based on cadence, as a decimal string. null for one-off meetings.

array

The highest-cost individual meetings in the period.

Show largest_meetings item fields

string

MeetCost internal meeting ID.

string | null

Meeting title.

string | null

Actual start datetime (ISO 8601).

integer

Number of attendees.

number

Actual duration in minutes.

string

Total cost, as a decimal string.

object | null

The rollout metric showing whether organisers act on nudges. Present only for org-wide scoped reports (finance and admin roles). null for team-scoped or own-meetings reports.

Show reduced_before_send fields

integer

Number of drafts that were edited at least once before sending.

integer

Drafts where the final estimate was lower than the first estimate.

integer

Drafts that were never committed (invite was not sent).

number

Percentage of revised drafts that were reduced.

string

Aggregate estimated cost reduction across all reduced drafts, as a decimal string.

Response example

{
  "period": "2026-W35",
  "period_start": "2026-08-24",
  "period_end": "2026-08-30",
  "scope": "org_wide",
  "currency": "USD",
  "total_spend": "18432.50",
  "meeting_count": 147,
  "person_hours": "612.5",
  "previous_total": "16890.00",
  "change_percent": 9.13,
  "by_team": [
    { "team_id": "eng", "team_name": "Engineering", "meetings": 52, "total": "7140.20" },
    { "team_id": "sales", "team_name": "Sales", "meetings": 41, "total": "5210.80" }
  ],
  "by_series": [
    {
      "series_id": "rrule-xyz",
      "title": "Weekly all-hands",
      "occurrences": 1,
      "total": "1840.00",
      "annualised": "95680.00"
    }
  ],
  "largest_meetings": [
    {
      "meeting_id": "d4e5f6...",
      "title": "Q3 planning",
      "started_at": "2026-08-26T13:00:00Z",
      "headcount": 34,
      "duration_minutes": "120",
      "total": "3210.40"
    }
  ],
  "reduced_before_send": {
    "drafts_with_revisions": 23,
    "reduced": 14,
    "abandoned": 5,
    "reduced_percent": 60.87,
    "estimated_saving": "2140.00"
  }
}

Example request

curl "https://meetcost.acme-corp.internal/api/v1/reports?period=monthly&anchor=2026-09-01" \
  -H "Authorization: Bearer <token>"

GET /api/v1/reports/export.csv

Downloads an aggregate CSV of the same report data. Applies the same role-scoping rules as the JSON endpoint — organiser, team_lead, finance, and admin callers may all call this endpoint, each receiving data at their own scope level. Participants receive 403. The CSV is aggregate-only: no column identifies an individual person’s cost, salary, or rate. Every call creates an audit record.

Query parameters

Same as GET /api/v1/reports: period (weekly|monthly) and optional anchor (YYYY-MM-DD).

Response

Returns text/csv with a Content-Disposition: attachment header. The filename includes the period label and start date:

Content-Disposition: attachment; filename="meetcost-2026-W35-2026-08-24.csv"

Example request

curl "https://meetcost.acme-corp.internal/api/v1/reports/export.csv?period=weekly" \
  -H "Authorization: Bearer <token>" \
  -o meetcost-report.csv

Every call to the CSV export writes an audit record. Automated scripts that call this endpoint repeatedly will produce a proportionally large audit trail. Schedule exports thoughtfully — a weekly download is typically sufficient for most compliance workflows.

Overview

Endpoints

Periodic Meeting Cost Reports and CSV Data Exports

Role-to-scope mapping

GET /api/v1/reports

Query parameters

Response body

Response example

Example request

GET /api/v1/reports/export.csv

Query parameters

Response

Example request

​Role-to-scope mapping

​GET /api/v1/reports

​Query parameters

​Response body

​Response example

​Example request

​GET /api/v1/reports/export.csv

​Query parameters

​Response

​Example request

Role-to-scope mapping

GET /api/v1/reports

Query parameters

Response body

Response example

Example request

GET /api/v1/reports/export.csv

Query parameters

Response

Example request