> ## 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. # Get session insights > Retrieve insights for a specific session with pagination. When no `insights_session` row exists for the given `sessionId` (caliperSessionId) — for example, immediately after a session starts but before the asynchronous Caliper ingestion pipeline has materialized the row — the endpoint returns `200` with an empty result (`insights: []`, `total: 0`, and a default session summary with zero duration). This mirrors the behavior of `getUserInsights` when no sessions match. Findings stamped `rolloutState=SHADOW` are omitted; unstamped (`null`) findings remain visible. ## OpenAPI ````yaml /openapi/learn-with-ai/platform-api.yaml get /insights/1.0/sessions/{sessionId} 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/{sessionId}: get: tags: - Insights summary: Get session insights description: >- Retrieve insights for a specific session with pagination. When no `insights_session` row exists for the given `sessionId` (caliperSessionId) — for example, immediately after a session starts but before the asynchronous Caliper ingestion pipeline has materialized the row — the endpoint returns `200` with an empty result (`insights: []`, `total: 0`, and a default session summary with zero duration). This mirrors the behavior of `getUserInsights` when no sessions match. Findings stamped `rolloutState=SHADOW` are omitted; unstamped (`null`) findings remain visible. operationId: getSessionInsights parameters: - name: sessionId in: path description: Session ID to retrieve insights for (URL-encoded if necessary) required: true schema: type: string - $ref: '#/components/parameters/limit1' - $ref: '#/components/parameters/offset' - name: isProctored in: query description: Optional flag to filter insights by proctored status required: false schema: type: boolean - $ref: '#/components/parameters/type' - $ref: '#/components/parameters/insightGroups' - $ref: '#/components/parameters/category' responses: '200': $ref: '#/components/responses/InsightsSuccess1' '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: 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 type: name: type in: query description: >- Comma-separated list of insight type slugs to filter by. Takes precedence over insightGroups, category, and default. required: false schema: type: string examples: - PhysicalVerbalSocializing,OnlineAppFocusSwitch style: form explode: false 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 category: name: category in: query description: >- Comma-separated list of categories to filter by. Takes precedence over the default but is overridden by type and insightGroups. required: false schema: type: string examples: - >- AcademicIntegrity,Observability,OnlineEnvironment,PhysicalEnvironment style: form explode: false responses: InsightsSuccess1: description: Successful response with insights and session summary content: application/json: schema: $ref: '#/components/schemas/PaginatedInsightsOutput' 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: PaginatedInsightsOutput: type: object description: Unified paginated insights response with session summary properties: session: $ref: '#/components/schemas/SessionSummaryOutput' description: Session summary information insights: type: array description: Array of insight objects items: $ref: '#/components/schemas/InsightOutput' 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: - session - insights - 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 SessionSummaryOutput: type: object description: Session summary information properties: 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) recordingS3Key: type: - string - 'null' description: S3 key of the session recording, null if no recording exists metadata: $ref: '#/components/schemas/InsightsSessionMetadata' isProctored: type: - boolean - 'null' description: >- Whether the session was proctored. Populated only for a single owning session; null for aggregate summaries that span multiple sessions. revokedAt: type: - string - 'null' format: date-time description: >- Timestamp when the session was quarantined (revoked), or null when it is not revoked. Downstream fail-closed consumers read this to distinguish a quarantined session from one that is not yet materialized. subject: $ref: '#/components/schemas/SessionSubject' subjectSource: $ref: '#/components/schemas/SessionSubjectSource' required: - startedAtTime - endedAtTime - durationInSeconds - wasteDurationInSeconds - wastePercentage - recordingS3Key - isProctored - revokedAt - subject - subjectSource InsightOutput: type: object description: Unified insight information properties: id: type: string format: uuid description: Unique identifier for the insight insightType: $ref: '#/components/schemas/InsightType' insightGroup: type: - string - 'null' description: >- Stable Insight Group slug for this insight's type; null when the type has no group (for example, Journal). The published set is served by GET /insights/1.0/insight-groups; it is not a fixed list. examples: - StayFocused reason: type: string description: Detailed reason or description for the insight startedAtTime: type: string format: date-time description: Timestamp when the insight period started endedAtTime: type: string format: date-time description: Timestamp when the insight period ended durationInSeconds: type: integer description: Duration of the insight in seconds version: $ref: '#/components/schemas/InsightVersion' messageVersion: type: - integer - 'null' description: Pinned catalog message bundle version; null for legacy insights rolloutState: type: - string - 'null' enum: - SHADOW - NOTIFY - ENFORCE description: >- Rollout stage recorded at detection for the student's school, not the school's current stage. Dashboard GETs (`getUserInsights`, `getSessionInsights`) omit `SHADOW`; `getSessionNotifications` may still return it. Null when no rollout policy governed the finding. required: - id - insightType - insightGroup - reason - startedAtTime - endedAtTime - durationInSeconds - version 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) InsightVersion: type: string description: Version of the insight maxLength: 16 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 ````