---
title: "Accounting analytics"
method: GET
path: "/analytics/accounting"
tags: ["Analytics"]
---

# Accounting analytics

`GET /analytics/accounting`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/analytics/accounting`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://joinways.app/oauth/authorize`, token URL `https://joinways.app/api/oauth/token`, scopes: `mcp.read`)

Realized revenue over the period (the Reports page "Finance" tab): revenue excl. tax of confirmed events dated by the event's start date (in the event's time zone), cancellation fees included and dated by the cancellation. An event's amount is its confirmed amount, else its latest accepted/signed quote, else the accepted platform amount; `coverage` says how many confirmed events have one. Also returns the current calendar year outlook (realized, booked ahead, forecast with an 80 % range).

**Changed in 1.3.0:** `monthly_accounting` is kept (count and revenue per event month, months with events only) but follows the period and amount rules above.
**Role permission:** `reports.view`.

## Query parameters

- `from` string, date
- `to` string, date
- `venues` string
- `compare` 'year' | 'previous' | 'none'

## Response `200`

Finance metrics for the period.

- AccountingAnalytics
  - `period` object: Effective period after defaults and caps.
    - `from` string, date
    - `to` string, date
    - `today` string, date: Today in the workspace time zone.
    - `timezone` string
  - `comparison` object, nullable
    - `mode` 'year' | 'previous'
    - `from` string, date
    - `to` string, date
  - `venue_ids` string[], nullable: Venue filter applied; `null` = all venues.
  - `currency` string: Workspace currency of every amount (amounts are excl. tax, 2 decimals).
  - `monthly_accounting` object: Legacy — `YYYY-MM` → events and revenue of that event month (months with events only).
  - `kpis` object
    - `revenue` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `cancellation_fees` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `events` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `events_with_amount` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `average_per_event` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `revenue_per_guest` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `guests` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
  - `monthly` object[]
    - `month` string
    - `revenue` number
    - `previous_revenue` number, nullable
    - `events` integer
    - `previous_events` integer, nullable
    - `cancellation_fees` number
  - `by_venue` object[]
    - `location_id` string, uuid
    - `name` string
    - `events` integer
    - `revenue` number
    - `share_pct` number, nullable
    - `average_per_event` number, nullable
    - `revenue_change_pct` number, nullable
  - `by_type` object[]
    - `event_type` string
    - `events` integer
    - `revenue` number
    - `share_pct` number, nullable
    - `average_per_event` number, nullable
  - `coverage` ReportCoverage: Confirmed/signed events with a known amount (`numerator`) out of all of them (`denominator`), and where the amount came from.
    - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
    - `numerator` integer
    - `denominator` integer
    - `from_event` integer, nullable
    - `from_quote` integer, nullable
    - `from_platform` integer, nullable
  - `year_outlook` object: Current calendar year (workspace time zone), whatever the period.
    - `year` integer
    - `from` string, date
    - `to` string, date
    - `realized` number: Revenue of events up to today included.
    - `secured` number: Realized + confirmed events to come this year.
    - `booked_ahead` number: `secured` − `realized`.
    - `forecast` object
      - `expected` number: `secured` + Σ option value × win probability.
      - `low` number: Lower bound of the 80 % range.
      - `high` number: Upper bound of the 80 % range.
      - `from_options` number: Open options dated in the period × probability to sign before the event date (survival model on each option's history). An option without amount counts at its estimated amount (similar confirmed events).
      - `from_unpriced_confirmed` number: Confirmed events still without amount, at their estimated amount × share of past confirmed events that received one.
      - `from_upcoming_inquiries` number: Revenue expected from inquiries not received yet (booking pace of past months).
      - `options` integer
    - `goal` object: Annual realized-revenue goal of the venues shown, the sum of the 12 monthly goals (same rule as the monthly goal). Amount and progress are null while a month has no goal.
      - `metric` 'realized_revenue'
      - `amount` number, nullable
      - `missing_months` string[]: Months (YYYY-MM) without a goal for the venues shown.
      - `secured_pct` number, nullable
      - `realized_pct` number, nullable
      - `expected_pct` number, nullable
      - `probability` number, nullable
      - `remaining` number, nullable
    - `monthly` object[]
      - `month` string
      - `booked` number
      - `expected_from_options` number
      - `expected_from_upcoming_inquiries` number: Revenue expected from inquiries not received yet (booking pace of past months).
      - `cumulative_secured` number
      - `cumulative_expected` number

## Other responses

- `400`: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
- `401`: Missing, invalid, expired or revoked bearer token (`unauthorized`).
- `403`: The token lacks the `mcp.read` scope, or its owner's role lacks the `reports.view` permission (reports carry revenue).
- `429`: Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.

---

[API](https://skmtc.dev/joinways/apis/joinways-public-api.md) · [All operations](https://skmtc.dev/joinways/apis/joinways-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/joinways/apis/joinways-public-api/revisions/39e84309953e?raw)