Papermark is the open-source DocSend alternative and secure data rooms with built-in analytics and custom domains.
API usage logging
Every public-API request emits one metadata-only usage event from
withTeam() via lib/api/usage.ts (emitApiUsage). No request bodies, query
values, or path-param values are ever logged.
Event shape
request_id, timestamp, team_id, token_id, user_id, subject_type, source, plan, mode, client, client_version, client_host, method, route, status, duration_ms, scopes_required, error_code
client—cli|mcp|mcp-remote|api(raw HTTP) |other, from thex-papermark-clientheader the CLI/MCP send.client_host— for MCP, the host the agent runs in (claude.ai,cursor, …).route— low-cardinality template, e.g./api/v1/links/:id.- Every response also carries an
x-request-idheader matchingrequest_id.
Sinks (both optional, inert until configured)
Configured via env (see .env.example). With neither set, events fall back to
a [api-usage] stdout line (also emitted in dev or when API_USAGE_STDOUT=1).
- Axiom (
AXIOM_TOKEN,AXIOM_DATASET, optionalAXIOM_EDGE) — raw events for search, dashboards, alerts, via the official@axiomhq/jsclient. Ingested with_time = timestamp. SetAXIOM_EDGEto a region edge domain (e.g.eu-central-1.aws.edge.axiom.co) for EU residency; leave blank for the US default. The client batches; we flush per request via Next'safter()so events survive a serverless freeze. - PostHog (
NEXT_PUBLIC_POSTHOG_KEY) —api_requestevents attributed to the team via group analytics ($groups.team). Only team-attributed requests are sent. Fire-and-forgetfetchwithkeepalive: true.
Starter Axiom (APL) queries — answering the four questions
Requests per team (last 7d):
['papermark-api'] | where _time > ago(7d)
| summarize requests = count() by team_id | sort by requests desc
By client + host ("from which clients"):
['papermark-api'] | where _time > ago(7d)
| summarize requests = count() by client, client_host | sort by requests desc
Top routes per team ("what calls"):
['papermark-api'] | where _time > ago(7d)
| summarize requests = count() by team_id, route | sort by requests desc
Active teams (WAU) + by client:
['papermark-api'] | where _time > ago(7d)
| summarize teams = dcount(team_id) by client
Error rate by route (last 24h):
['papermark-api'] | where _time > ago(24h)
| summarize total = count(), errors = countif(status >= 400) by route
| extend error_rate = round(100.0 * errors / total, 1) | sort by error_rate desc
p50/p95 latency by route:
['papermark-api'] | where _time > ago(24h)
| summarize p50 = percentile(duration_ms, 50), p95 = percentile(duration_ms, 95) by route
PostHog setup
- Create a group type named
team(Project settings → Groups). - Build insights on the
api_requestevent, breaking down by groupteam.- Active teams = unique
teamgroups over the period. - Adoption by client = breakdown by the
clientproperty. - Retention = group-based retention on
team.
- Active teams = unique
Suggested Axiom monitors (Phase 3)
- 5xx spike:
countif(status >= 500)over 5m above a threshold. - Per-team abuse: a single
team_idexceeding N requests/min. - Error-rate by route crossing a threshold.