Returns one row per engagement session for your organization over a date range — real product usage, with each session's duration and event count. A session is a PostHog $session_id: a window of activity that closes after 30 minutes of inactivity, not a login. Use this for an accurate picture of how much time researchers actually spend in the product.

This is distinct from GET /v2/usage/logins/, which lists raw authentication events. One login can span several engagement sessions, and a returning user can open a new session without logging in again. Correlate the two by joining on user_id and the session's time range.

Authentication. OAuth 2.1 bearer token (Authorization: Bearer <token>) with the usage:read scope, consented at the organization level; access is limited to organizations enabled for the usage API. The authenticated user must be an organization admin or non-researcher admin.

A partner credential reads the same metrics for one client organization by naming it in the assertion's outset_org claim; the consent, role and allow-list conditions above are properties of a user-delegated token and have no partner analogue.

Date range. start_date and end_date are both required and inclusive, in YYYY-MM-DD (RFC 3339 full-date) format, evaluated in UTC. The range may span at most 366 days.

Pagination. Cursor-paginated: when has_more is true, pass the returned next_cursor back as the cursor query parameter. Page size defaults to 50 and is capped at 200.

Session data is sourced from an upstream analytics provider. A 400 with code=result_too_large means the requested range should be shortened; transient 502 (provider unavailable) and 503 (data being prepared — retry after Retry-After) responses should be retried with backoff.

Requires the usage:read scope, on a user-delegated token or a partner credential.