1. Guides
Handwrite Team
  • Handwrite Team
    • Teams
      • README — GET /api/v1/orgs
      • README — POST /api/v1/orgs
      • README — GET /api/v1/orgs/{id}
      • README — PATCH /api/v1/orgs/{id}
      • README — DELETE /api/v1/orgs/{id}
      • Your teams and classes
      • Create a team or class
      • One of your organisations
      • Rename a team (owner or admin)
      • Delete with its memberships, invitations, documents and shares (owner)
    • Membership
      • README — GET /api/v1/orgs/invitations
      • README — POST /api/v1/orgs/invitations/{inviteId}/accept
      • README — POST /api/v1/orgs/invitations/{inviteId}/decline
      • README — GET /api/v1/orgs/{id}/members
      • README — POST /api/v1/orgs/{id}/members
      • README — PATCH /api/v1/orgs/{id}/members/{principal}
      • README — DELETE /api/v1/orgs/{id}/members/{principal}
      • README — POST /api/v1/orgs/{id}/leave
      • README — GET /api/v1/orgs/{id}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Organisation invitations to your verified email
      • Join with the invited role
      • Decline an organisation invitation
      • Members (students see teachers and themselves)
      • Add a person (managers)
      • Change a role; owner transfers a team
      • Remove a member (managers) or yourself
      • Leave (not the owner)
      • Pending email invitations (managers)
      • Invite an email (managers)
      • Withdraw an invitation (managers)
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents the organisation owns
    • Billing and usage
      • README — GET /api/v1/orgs/{id}/billing
      • README — GET /api/v1/orgs/{id}/usage
      • README — GET /api/v1/orgs/{id}/usage/live
      • README — GET /api/v1/orgs/{id}/members/{principal}/usage
      • README — GET /api/v1/orgs/{id}/insights
      • Plan, status and seats per role (billing.read)
      • Usage per day and member (admins, managers, billing)
      • The last 60 minutes per member (admins, managers, billing)
      • One member's usage (usage.read, or yourself)
      • How people collaborate on the org's documents
    • Policies
      • README — GET /api/v1/orgs/{id}/policies
      • README — PUT /api/v1/orgs/{id}/policies
      • README — GET /api/v1/orgs/{id}/members/{principal}/policy
      • README — PUT /api/v1/orgs/{id}/members/{principal}/policy
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/policy
      • Org-wide policy rules (policies.read)
      • Replace the org-wide rules (admins)
      • A member's override and what applies to them
      • Replace a member's override (admins; managers for members)
      • Remove a member's override
    • Managed tokens
      • README — GET /api/v1/orgs/{id}/members/{principal}/tokens
      • README — POST /api/v1/orgs/{id}/members/{principal}/tokens
      • README — DELETE /api/v1/orgs/{id}/members/{principal}/tokens/{tokenId}
      • Managed tokens issued to a member (tokens.read)
      • Issue a managed fine-grained token (admins, billing)
      • Revoke a managed token (admins, billing)
    • Guides
      • Start here — Team app integration
      • Team API specification notes
      • Team socket specification notes
      • Team live socket — README
      • Team roles and access model
      • Team credentials and developer setup
      • Team SSO and portal workflows
      • Team policies, plans and seats
      • Team usage and collaboration insights
      • Team webhook delivery — README
  1. Guides

Team usage and collaboration insights

The usage APIs return counts and time windows. They do not expose raw document text, keystrokes, IP addresses or device histories. Present these as activity indicators with context, not a measure of a person's productivity or proof of authorship.
EndpointPurposeHandling
GET /api/v1/orgs/{id}/usageDaily organisation/member totalsdays=1–90, default 30; JSON or CSV.
GET /api/v1/orgs/{id}/usage/liveLast 60 minutes plus current totalsPoll HTTP with ETag; handle 304. Not a WebSocket endpoint.
GET /api/v1/orgs/{id}/members/{principal}/usageOne member's permitted detailSelf access or usage.read, with visibility filtering.
GET /api/v1/orgs/{id}/insightsCollaboration across team documentsrange=7/30/90 or from/to up to 365 UTC days.
Owners/admins, managers and billing may view organisation usage when the plan includes it. Team managers always receive team-document-only counters. With the default orgDocuments visibility, other permitted viewers also receive document-only counters; hidden fields identify counters that must not be treated as measured zeroes. Document names can be null when the viewer lacks content access.
The live snapshot has a 10-second per-instance cache. “Active now” means qualifying activity in the recent two-minute window; it is not guaranteed online presence. Use a restrained polling interval, conditional requests and backoff. Actual editing presence is part of the separate live-room protocol.
Insights gives owner/admin/manager the full allowed view. Member tier gets only its own share; billing and developer are not automatically entitled to it. Handle the returned shape/redaction instead of reconstituting other people's activity from separate calls.
The source retention descriptions are 48 hours for minute counters, 90 days for daily usage and 365 days for collaboration summaries. These are implementation retention values, not a promise of complete historical analytics or proof that every live TTL/lifecycle setting was inspected. Reads of other people's usage/insights are audited with throttling.
Source: usage-org.ts, usage-schemas.ts, events.ts, insights.ts.
Modified at 2026-10-26 13:14:15
Previous
Team policies, plans and seats
Next
Team webhook delivery — README
Built with