> ## Documentation Index > Fetch the complete documentation index at: https://docs.timeback.com/llms.txt > Use this file to discover all available pages before exploring further. # List sessions with waste and insight enrichment > Retrieve paginated list of sessions with organization or user scoping, enriched with waste metrics and insights summary. Supports filtering by waste percentage, waste duration, and insight types. Enrichment for insightsSummary can be selected independently of the session filter via enrichmentInsightTypes and enrichmentInsightCategories. ## OpenAPI ````yaml /openapi/learn-with-ai/platform-api.yaml get /insights/1.0/sessions openapi: 3.1.1 info: title: TimeBack Platform API description: >- RESTful API for the TimeBack Platform. Covers authentication, rostering, curriculum, insights, assessments, content grading, and more. version: 2026.09.10.1 servers: - url: https://platform.dev.timeback.com description: integration security: [] tags: - name: Auth description: Authentication and authorization endpoints - name: Organizations description: Organizations module contains all endpoints around organization management - name: Applications description: Applications module contains all endpoints for managing LTI applications - name: Users description: >- Users module contains all endpoints around user creation, update and consultation - name: Students description: Students module contains all endpoints around student management - name: Demographics description: >- Demographics module contains all endpoints around demographics consultation - name: Consent description: >- Initiate and query TimeBack parental consent for a student, backed by an immutable audit trail. - name: Classes description: Classes module contains all endpoints around class management - name: Courses description: Courses module contains all endpoints around course management - name: Enrollments description: Enrollments module contains all endpoints around enrollment consultation - name: CASE description: Competency and Academic Standards Exchange (CASE) 1.1 API - name: Curriculum description: Curriculum module contains endpoints for managing curriculum data - name: Competency Track description: Competency track endpoints - name: Content Grading description: >- Registration and management of graders for free-response content items — bring-your-own external graders (Tier 2) and, once shipped, platform-managed grading prompts (Tier 1). - name: Caliper description: The Caliper module contains all endpoints around Caliper Analytics - name: Insights description: Coaching insights and session analytics endpoints paths: /insights/1.0/sessions: get: tags: - Insights summary: List sessions with waste and insight enrichment description: >- Retrieve paginated list of sessions with organization or user scoping, enriched with waste metrics and insights summary. Supports filtering by waste percentage, waste duration, and insight types. Enrichment for insightsSummary can be selected independently of the session filter via enrichmentInsightTypes and enrichmentInsightCategories. operationId: getOrgSessions parameters: - name: orgId in: query description: >- Filter by organization ID. Returns sessions for users whose primary organization is this org, or who have a student role in the org. At least one of orgId or userId must be provided. required: false schema: type: string format: uuid - name: userId in: query description: Filter by user ID. At least one of orgId or userId must be provided. required: false schema: type: string format: uuid - name: applicationId in: query description: Filter by application ID required: false schema: type: string format: uuid - name: after in: query description: Filter sessions starting after this timestamp (ISO 8601, inclusive) required: false schema: type: string format: date-time - name: before in: query description: Filter sessions starting before this timestamp (ISO 8601, inclusive) required: false schema: type: string format: date-time - name: minWastePercentage in: query description: Minimum waste percentage (0-100, inclusive) required: false schema: type: number minimum: 0 maximum: 100 - name: maxWastePercentage in: query description: Maximum waste percentage (0-100, inclusive) required: false schema: type: number minimum: 0 maximum: 100 - name: minWasteDurationInSeconds in: query description: Minimum waste duration in seconds (inclusive) required: false schema: type: number minimum: 0 - name: maxWasteDurationInSeconds in: query description: Maximum waste duration in seconds (inclusive) required: false schema: type: number minimum: 0 - name: insightTypes in: query description: >- Comma-separated list of insight types. Filters to sessions containing at least one visible insight of the specified types (OR logic), after type-visibility ACL. Takes precedence over insightGroups. When set, insightsSummary counts those same ACL-visible types only. When none of the requested types are visible to the client, the page is empty. When unset, insightsSummary and waste metrics reflect the default user-facing set (waste + proctoring). Under a type filter, waste metrics use the same formula but only from waste types within the fetched allowlist. Decides insightsSummary only when neither enrichmentInsightTypes nor enrichmentInsightCategories is present. required: false schema: type: string examples: - Idling,AwayFromSeat style: form explode: false - $ref: '#/components/parameters/insightGroups' - name: enrichmentInsightTypes in: query description: >- Comma-separated list of insight type slugs used only to widen insightsSummary and the fetched insight set. Does not contribute to the insightTypes session filter. Waste metrics are computed from the fetched set, so when minWastePercentage, maxWastePercentage, or the waste-duration bounds are also present, a waste-free enrichment set can empty or shrink the result page. Internal-only types are dropped for external credentials rather than returning an error; unknown slugs return 400. When set (alone or with enrichmentInsightCategories) it replaces the insightTypes-aligned enrichment and the default enrichment. required: false schema: type: string examples: - ObservabilityCameraWorking,AcademicIntegrityStayInTheTest - name: enrichmentInsightCategories in: query description: >- Comma-separated list of insight categories expanded server-side to their client-visible type slugs, used only to widen insightsSummary and the fetched insight set. Does not contribute to the insightTypes session filter. Waste metrics are computed from the fetched set, so when minWastePercentage, maxWastePercentage, or the waste-duration bounds are also present, a waste-free enrichment set can empty or shrink the result page. Unknown categories contribute no types rather than returning an error, so a request whose resolved enrichment set is empty returns its sessions with an empty insightsSummary and zero waste metrics. required: false schema: type: string examples: - Observability,AcademicIntegrity - name: isProctored in: query description: Filter by proctored status required: false schema: type: boolean - name: webcamEnabled in: query description: Filter by webcam enabled status required: false schema: type: boolean - name: enforcement in: query description: >- Comma-separated popup and enforcement outcomes. Narrows the result set (including total and pagination) to sessions matching ANY of the tokens (OR logic): auto_stopped (a forced-end occurred), warning_issued (at least one ENFORCE warning popup was shown, falling back to legacy warning events for sessions with no presentation ledger), or notification_shown (at least one NOTIFY popup was shown). Unknown tokens return 400. required: false schema: type: string examples: - auto_stopped,warning_issued,notification_shown - name: includeEnforcement in: query description: >- When true, widens an insightTypes filter so proctored sessions that had an enforcement event (warning_accrued / warning_displayed / forced_end) surface even when they have no visible insight of the requested types. Has no effect without insightTypes. Defaults to false. required: false schema: type: boolean default: false - $ref: '#/components/parameters/limit1' - $ref: '#/components/parameters/offset' responses: '200': $ref: '#/components/responses/EnrichedSessionsSuccess' '400': $ref: '#/components/responses/BadRequest18' '401': $ref: '#/components/responses/Unauthorized8' '403': $ref: '#/components/responses/Forbidden7' '500': $ref: '#/components/responses/InternalError18' security: - CognitoUserPoolAuthorizer: - https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly components: parameters: insightGroups: name: insightGroups in: query description: >- Comma-separated list of stable Insight Group slugs to filter by. Display names are served by GET /insights/1.0/insight-groups. Takes precedence over category and default, but is overridden by type (or insightTypes on session endpoints). On endpoints that return insights, selects matching insights. On endpoints that return sessions, a session is returned only if it carries at least one caller-visible insight of a member type, and the session's metrics scope to the filter. required: false schema: type: string examples: - StayFocused,DistractionFreeSpace style: form explode: false limit1: name: limit in: query description: Maximum number of items to return required: false schema: type: integer minimum: 1 maximum: 100 default: 20 offset: name: offset in: query description: Number of items to skip required: false schema: type: integer minimum: 0 default: 0 responses: EnrichedSessionsSuccess: description: Successful response with enriched sessions content: application/json: schema: $ref: '#/components/schemas/PaginatedEnrichedSessionsOutput' BadRequest18: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: default: value: error: Bad request message: Invalid request parameters Unauthorized8: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: default: value: error: Unauthorized request message: Unauthorized request Forbidden7: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: default: value: error: Access forbidden message: Access forbidden InternalError18: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: default: value: error: Internal server error message: Internal server error schemas: PaginatedEnrichedSessionsOutput: type: object description: Paginated list of enriched sessions properties: sessions: type: array description: Array of enriched session objects items: $ref: '#/components/schemas/EnrichedSessionOutput' offset: type: integer description: Number of items skipped in the result set limit: type: integer description: Maximum number of items returned total: type: integer description: Total number of items available required: - sessions - offset - limit - total ApiError: type: object description: API error response properties: error: type: string description: Error type message: type: string description: Error message required: - error - message EnrichedSessionOutput: type: object description: Session enriched with waste metrics and insights summary properties: id: type: string description: Session identifier (caliper session ID) userId: type: string format: uuid description: User ID associated with this session applicationId: type: string format: uuid description: Application ID associated with this session startedAtTime: type: string format: date-time description: Timestamp when the session started endedAtTime: type: string format: date-time description: Timestamp when the session ended durationInSeconds: type: integer description: Total duration of the session in seconds wasteDurationInSeconds: type: integer description: Total waste duration of the session in seconds wastePercentage: type: integer description: Percentage of session time that was waste (0-100) isProctored: type: boolean description: Whether this session is proctored webcamEnabled: type: boolean description: Whether the webcam was enabled for this session recordingStartedAtTime: type: - string - 'null' format: date-time description: Timestamp when the recording started recordingEndedAtTime: type: - string - 'null' format: date-time description: Timestamp when the recording ended recordingS3Key: type: - string - 'null' description: S3 key for the associated proctoring recording insightsSummary: $ref: '#/components/schemas/InsightsSummary' enforcementSummary: type: object description: >- Popup and enforcement summary for the session. Present for proctored sessions and for any session with popup history (presentation ledger rows); omitted otherwise. Counts cover popups shown to the student — an offer superseded before display is not counted. properties: autoStopped: type: boolean description: >- Whether the session was automatically stopped (a forced-end enforcement event exists) warningCount: type: integer description: >- Number of ENFORCE warning popups shown during the session, excluding terminal suspensions. For sessions with no presentation ledger, falls back to the legacy distinct-warning-event count (a warning that both accrued a strike and was confirmed as displayed counts once). notificationCount: type: integer description: >- Number of NOTIFY popups shown during the session. Zero for pre-cutover sessions with no presentation ledger. required: - autoStopped - warningCount - notificationCount metadata: $ref: '#/components/schemas/InsightsSessionMetadata' subject: $ref: '#/components/schemas/SessionSubject' subjectSource: $ref: '#/components/schemas/SessionSubjectSource' required: - id - userId - applicationId - startedAtTime - endedAtTime - durationInSeconds - wasteDurationInSeconds - wastePercentage - isProctored - webcamEnabled - recordingStartedAtTime - recordingEndedAtTime - recordingS3Key - insightsSummary - subject - subjectSource InsightsSummary: type: object description: Summary of insights present in a session properties: insightTypes: type: array description: Distinct insight types present in the session items: $ref: '#/components/schemas/InsightType' totalCount: type: integer description: Total number of visible insights in the session insightCountsByType: type: array description: Per-insight-type breakdown of visible insight counts items: $ref: '#/components/schemas/InsightCountByType' required: - insightTypes - totalCount - insightCountsByType InsightsSessionMetadata: type: - object - 'null' additionalProperties: true description: Opaque session metadata object SessionSubject: type: - string - 'null' description: >- Academic subject attributed to this learning session. Null means not yet decided (no vision-end upsert). Unknown is an explicit value meaning looked and could not say. Values: Reading, Language, Vocabulary, Social Studies, Writing, Science, FastMath, Math, Unknown. enum: - Reading - Language - Vocabulary - Social Studies - Writing - Science - FastMath - Math - Unknown SessionSubjectSource: type: - string - 'null' description: >- How subject was decided: app (single-subject LTI application shortcut), journal (vision journal classification), or none (fallback Unknown). Null when subject is null. enum: - app - journal - none InsightType: type: string description: >- Insight type slug (data-driven, see GET /insights/1.0/types for available types) InsightCountByType: type: object description: Count of visible insights for a single insight type properties: insightType: $ref: '#/components/schemas/InsightType' count: type: integer description: Number of visible insights of this type in the session required: - insightType - count securitySchemes: CognitoUserPoolAuthorizer: type: oauth2 description: >- OAuth 2.0 client credentials flow. Contact timeback@trilogy.com to request credentials for your application. flows: clientCredentials: tokenUrl: https://platform.dev.timeback.com/auth/1.0/token scopes: https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly: roster readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly: roster-core readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput: roster createput https://purl.imsglobal.org/spec/lti/v1p3/scope/lti.readonly: lti readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster-demographics.readonly: roster-demographics readonly https://timeback-platform.trilogy.com/consent/scope/consent.write: consent write https://timeback-platform.trilogy.com/consent/scope/consent.read: consent read https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.createput: roster-core createput https://purl.imsglobal.org/spec/or/v1p2/scope/roster.delete: roster delete https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.delete: roster-core delete https://purl.imsglobal.org/spec/case/v1p0/scope/case.readonly: case readonly https://purl.imsglobal.org/spec/case/v1p0/scope/case.createput: case createput https://purl.imsglobal.org/spec/case/v1p0/scope/case.delete: case delete https://timeback-platform.trilogy.com/competency-track/scope/competency-track.readonly: competency-track readonly https://timeback-platform.trilogy.com/competency-track/scope/competency-track.write: competency-track write https://timeback-platform.trilogy.com/competency-track/scope/competency-track.delete: competency-track delete https://timeback-platform.trilogy.com/content/scope/content.write: content write https://timeback-platform.trilogy.com/content/scope/content.read: content read https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write: events write https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly: events readonly https://timeback-platform.trilogy.com/webhooks/scope/webhooks.write: webhooks write https://timeback-platform.trilogy.com/webhooks/scope/webhooks.read: webhooks read https://timeback-platform.trilogy.com/webhooks/scope/webhooks.delete: webhooks delete ````