---
title: "Inquiry analytics"
method: GET
path: "/analytics/events"
tags: ["Analytics"]
---

# Inquiry analytics

`GET /analytics/events`

## Request

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

Inquiries received over the period (the Reports page "Inquiries" tab): received, accepted, rejected, pending, quoted and confirmed counts, acceptance rate (accepted / received) and win rate (confirmed / received, reception cohort), monthly series, breakdown by source and by venue, processing times. Inquiries are dated by their reception.

**Changed in 1.3.0:** this endpoint used to count events by status and by event month over a fixed 12-month window. It now reports inquiries with the page's definitions; the legacy `analytics` map is kept but holds inquiry counts per reception month.
**Role permission:** `reports.view`.

## Query parameters

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

## Response `200`

Inquiry metrics for the period.

- InquiryAnalytics
  - `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).
  - `analytics` object: Legacy — `YYYY-MM` → inquiry counts of that reception month.
  - `kpis` object
    - `received` 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.
    - `accepted` 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.
    - `rejected` 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.
    - `pending` 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.
    - `quoted` 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.
    - `confirmed` 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.
    - `acceptance_rate` 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.
    - `win_rate` 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.
  - `monthly` object[]
    - `month` string
    - `received` integer
    - `previous_received` integer, nullable
    - `accepted` integer
    - `rejected` integer
    - `pending` integer
  - `by_source` object[]
    - `source_key` string
    - `label` string
    - `received` integer
    - `share_pct` number, nullable
    - `received_change_pct` number, nullable
    - `accepted` integer
    - `acceptance_rate` 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
    - `quoted` integer
    - `confirmed` integer
    - `win_rate` 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
    - `lost` integer
    - `lost_slot` integer: Lost because the date was taken.
    - `from_inbox` integer
    - `manual_email` integer
    - `manual_phone` integer
  - `by_venue` object[]
    - `location_id` string, uuid
    - `name` string, nullable
    - `received` integer
    - `share_pct` number, nullable
    - `received_change_pct` number, nullable
    - `accepted` integer
    - `acceptance_rate` 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
    - `pending` integer
    - `quoted` integer
    - `confirmed` integer
    - `win_rate` 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
  - `processing` object, nullable: Time from reception to accept/reject in Joinways (calendar hours).
    - `processed` integer
    - `under_1h` integer
    - `h1_4` integer
    - `h4_24` integer
    - `over_24h` integer
    - `avg_hours` number, nullable
    - `median_hours` number, nullable

## 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)