1. Plan and usage
Handwrite Classroom
  • Handwrite Classroom
    • Start here — Classroom for developers
    • Classroom API specification notes
    • Classroom socket specification notes
    • Classroom live socket — README
    • Classroom identities, credentials and roles
    • School and student workflows
    • Classroom policy and data-use notes
    • Class setup
      • 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}
      • Class setup API — README
      • Choose a class from the returned organisations
      • Create an ordinary class
      • Read the selected class
      • Rename a class
      • Delete an ordinary class
    • Invitations
      • 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}/invitations
      • README — POST /api/v1/orgs/{id}/invitations
      • README — DELETE /api/v1/orgs/{id}/invitations/{inviteId}
      • Invitations API — README
      • Read invitations to the signed-in person
      • Accept a class invitation
      • Decline a class invitation
      • List pending class invitations
      • Invite a person by email
      • Cancel a pending invitation
    • People
      • 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
      • People API — README
      • Read the visible membership roster
      • Add an existing person to a class
      • Change a class member role
      • Remove an ordinary class membership
      • Leave an ordinary class
    • Documents
      • README — GET /api/v1/orgs/{id}/documents
      • Documents API — README
      • List class-owned documents
    • Plan 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 and usage API — README
      • Read classroom plan and seat information
        GET
      • Read classroom usage totals
        GET
      • Read the recent classroom activity window
        GET
      • Read one member usage
        GET
      • Read classroom collaboration insights
        GET
    • 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
      • Policies API — README
      • Read class-wide policy
      • Replace class-wide policy rules
      • Read one member policy
      • Replace one member policy override
      • Clear one member 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 API — README
      • List tokens issued to a member
      • Issue a managed student token
      • Revoke a managed token
  1. Plan and usage

README — GET /api/v1/orgs/{id}/usage/live

Read the recent classroom activity window#

GET /api/v1/orgs/{id}/usage/live · Operation ID: getOrgLiveUsage

Application use#

This is an HTTP snapshot of the last 60 minutes, not a WebSocket or SSE feed. Poll with If-None-Match and handle 304 without parsing a body. Active status means recent counted activity, not proof a student is watching a particular page. Preserve the returned collection/retention disclosure.

Authentication and permission#

Bearer credential with orgs:read. usage.read: teacher, co-teacher or billing; orgs:read and plan usage feature.
Scopes, membership, current role, effective policy and applicable plan checks all apply. A managed student token cannot grant organisation-management authority. A student-pool login JWT is not a public-API bearer credential. See Classroom identity and roles.

Example#

Replace placeholders using an authorised disposable test class. Mutation examples change real data when run. Keep tokens on the server; never copy student credentials into diagnostics.
curl --fail-with-body -X GET 'https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/usage/live' \
  -H "Authorization: Bearer $HANDWRITE_API_TOKEN"

Parameters#

NameInRequiredDetails
idpathYesAn organisation ID (org_…).
If-None-MatchheaderNo{"type":"string"}

Responses and recovery#

StatusMeaningFormat
200The live table.application/json
304Unchanged since the ETag you sent.No response body specified
401unauthorized: no token, or it's invalid, revoked or expired.application/json
403insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request).application/json
404not_found: it doesn't exist or you can't see it (never 403 for documents you can't see).application/json
429rate_limited (burst or daily cap) or quota_exceeded (no characters left).application/json
500internal_error.application/json
The paired API reference holds the shared machine-readable schema. Additional role, policy, seat and plan failures are described in API specification notes. Do not parse 204 or 304 responses as JSON, and do not treat 403 as a transient retry.
Modified at 2026-10-26 13:24:24
Previous
README — GET /api/v1/orgs/{id}/usage
Next
README — GET /api/v1/orgs/{id}/members/{principal}/usage
Built with