---
title: "Reports overview"
method: GET
path: "/analytics/overview"
tags: ["Analytics"]
---

# Reports overview

`GET /analytics/overview`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/analytics/overview`
- 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`)

The Reports page overview, on fixed windows relative to today (only `venues` applies): signed revenue month to date against the same days one year earlier, monthly goal progress, revenue booked from today to the end of the 6th month, open pipeline, win rate over the last 12 months against the 12 before, median first response time over the last 30 days against the 90 before, up to 3 computed insights, action items and a 12-month trend with a 3-month forecast.
**Role permission:** `reports.view`.

## Query parameters

- `venues` string

## Response `200`

Overview of the workspace.

- ReportsOverview
  - `today` string, date
  - `timezone` string
  - `venue_ids` string[], nullable
  - `currency` string
  - `month` object
    - `month` string
    - `from` string, date
    - `to` string, date
    - `days_elapsed` integer
    - `days_in_month` integer
  - `month_to_date` object
    - `signed_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.
    - `previous_from` string, date
    - `previous_to` string, date
    - `signed` integer
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `month_revenue` object: Revenue of confirmed events dated in the current month (event date, as in accounting), which the goal measures.
    - `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.
    - `realized_to_date` number: Events already past, up to today.
    - `events` integer
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `forecast` object, nullable: Secured revenue plus the month's options weighted by their signing probability, with an 80 % range.
      - `expected` number
      - `low` number
      - `high` number
      - `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).
    - `like_for_like` object, nullable: Month revenue without the venues opened or closed since last year (null when every venue was open both years). A venue is opened since last year when it had no confirmed event in the 12 months up to the same month last year, closed when it had none in the last 12 months.
      - `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.
      - `opened_venues` object[]
        - `location_id` string, uuid
        - `revenue` number
      - `closed_venues` object[]
        - `location_id` string, uuid
        - `previous_revenue` number
  - `goal` object, nullable: Monthly realized-revenue goal, measured on month_revenue. All venues shown: the workspace goal, else the sum of the venue goals. Venue filter: the sum of the shown venues' goals. A sum is only given when every venue shown has a goal (see goal_missing_venues).
    - `metric` 'realized_revenue'
    - `amount` number
    - `secured_pct` number: Confirmed events of the month / goal.
    - `realized_pct` number: Events already past / goal.
    - `expected_pct` number, nullable: Forecast (secured + weighted options) / goal.
    - `probability` number, nullable: Probability (0–1) of reaching the goal.
    - `remaining` number: Goal minus secured, ≥ 0.
  - `goal_missing_venues` integer: Venues shown without a goal this month while others have one. goal is then null (incomplete goal).
  - `booked_ahead` object
    - `from` string, date
    - `to` string, date
    - `revenue` number
    - `events` integer
  - `pipeline` object
    - `open_options` integer
    - `valued_options` integer
    - `value` number
    - `weighted_value` number, nullable
  - `win_rate_12_months` ReportRate: A rate with its numerator and denominator.
    - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
    - `numerator` integer
    - `denominator` integer
    - `previous_pct` number, nullable
    - `change_points` number, nullable: Difference in percentage points with the comparison period.
  - `first_response` object
    - `median_business_minutes` number, nullable
    - `previous_median_business_minutes` number, nullable
    - `answered` integer
  - `insights` object[]: Up to 3 computed findings, each with `kind` (`venueDriver`, `sourceVolume`, `venueConversion`, `responseTime`), `tone` (`up`/`down`), `weight` and kind-specific fields (`location_id`, `source_key`, `delta`, `share`, `recent`, `baseline`, `change`, `recent_pct`, `baseline_pct`, `closed`, `recent_minutes`, `baseline_minutes`).
  - `actions` object
    - `expiring_quotes` object: Options whose quote expires within 7 days.
      - `count` integer
      - `value` number
      - `event_ids` string[]
    - `viewed_quotes` object: Quotes opened at least twice, last viewed within 7 days.
      - `count` integer
      - `value` number
      - `event_ids` string[]
    - `pending_inquiries` object: Inquiries of the last 30 days still to process.
      - `pending` integer
      - `over_24h` integer
      - `oldest_at` string, date-time, nullable
    - `confirmed_without_amount` integer
  - `trend` object[]: 11 past months, the current month and 3 months ahead (revenue by event month).
    - `month` string
    - `future` boolean
    - `booked` number
    - `previous` number: Same month one year earlier.
    - `events` integer
    - `forecast` object, nullable
      - `expected` number
      - `low` number
      - `high` number
      - `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).
    - `goal` number, nullable: Realized-revenue goal of the month for the venues shown (same rule as goal). Null when not set or incomplete.
    - `goal_probability` number, nullable: Upcoming months with a goal: probability (0-1) of reaching it, read from the simulated month (same model as goal.probability). Null for past months or without goal.
  - `annotations` object[]
    - `day` string, date
    - `label` string
    - `location_id` string, uuid, nullable
  - `by_venue` object[]
    - `location_id` string, uuid
    - `name` string, nullable
    - `month_revenue` number
    - `previous_month_revenue` number
    - `change_pct` number, nullable
    - `goal` number, nullable
    - `goal_pct` number, nullable
    - `win_rate_12_months` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `by_source` object[]: Top 6 sources by inquiries received over 12 months.
    - `source_key` string
    - `label` string
    - `received_12_months` integer
    - `win_rate_12_months` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `signed_revenue_12_months` 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)