List sessions with waste and insight enrichment

curl --request GET \
  --url https://platform.dev.timeback.com/insights/1.0/sessions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://platform.dev.timeback.com/insights/1.0/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.dev.timeback.com/insights/1.0/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.dev.timeback.com/insights/1.0/sessions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://platform.dev.timeback.com/insights/1.0/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "sessions": [
    {
      "id": "<string>",
      "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "applicationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "startedAtTime": "2023-11-07T05:31:56Z",
      "endedAtTime": "2023-11-07T05:31:56Z",
      "durationInSeconds": 123,
      "wasteDurationInSeconds": 123,
      "wastePercentage": 123,
      "isProctored": true,
      "webcamEnabled": true,
      "recordingStartedAtTime": "2023-11-07T05:31:56Z",
      "recordingEndedAtTime": "2023-11-07T05:31:56Z",
      "recordingS3Key": "<string>",
      "insightsSummary": {
        "insightTypes": [
          "<string>"
        ],
        "totalCount": 123,
        "insightCountsByType": [
          {
            "insightType": "<string>",
            "count": 123
          }
        ]
      },
      "subject": "Reading",
      "subjectSource": "app",
      "enforcementSummary": {
        "autoStopped": true,
        "warningCount": 123,
        "notificationCount": 123
      },
      "metadata": {}
    }
  ],
  "offset": 123,
  "limit": 123,
  "total": 123
}

{
  "error": "Bad request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized request",
  "message": "Unauthorized request"
}

{
  "error": "Access forbidden",
  "message": "Access forbidden"
}

{
  "error": "Internal server error",
  "message": "Internal server error"
}

GET

insights

1.0

sessions

List sessions with waste and insight enrichment

curl --request GET \
  --url https://platform.dev.timeback.com/insights/1.0/sessions \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://platform.dev.timeback.com/insights/1.0/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.dev.timeback.com/insights/1.0/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.dev.timeback.com/insights/1.0/sessions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://platform.dev.timeback.com/insights/1.0/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "sessions": [
    {
      "id": "<string>",
      "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "applicationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "startedAtTime": "2023-11-07T05:31:56Z",
      "endedAtTime": "2023-11-07T05:31:56Z",
      "durationInSeconds": 123,
      "wasteDurationInSeconds": 123,
      "wastePercentage": 123,
      "isProctored": true,
      "webcamEnabled": true,
      "recordingStartedAtTime": "2023-11-07T05:31:56Z",
      "recordingEndedAtTime": "2023-11-07T05:31:56Z",
      "recordingS3Key": "<string>",
      "insightsSummary": {
        "insightTypes": [
          "<string>"
        ],
        "totalCount": 123,
        "insightCountsByType": [
          {
            "insightType": "<string>",
            "count": 123
          }
        ]
      },
      "subject": "Reading",
      "subjectSource": "app",
      "enforcementSummary": {
        "autoStopped": true,
        "warningCount": 123,
        "notificationCount": 123
      },
      "metadata": {}
    }
  ],
  "offset": 123,
  "limit": 123,
  "total": 123
}

{
  "error": "Bad request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized request",
  "message": "Unauthorized request"
}

{
  "error": "Access forbidden",
  "message": "Access forbidden"
}

{
  "error": "Internal server error",
  "message": "Internal server error"
}

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials flow. Contact timeback@trilogy.com to request credentials for your application.

Query Parameters

orgId

string<uuid>

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.

userId

string<uuid>

Filter by user ID. At least one of orgId or userId must be provided.

applicationId

string<uuid>

Filter by application ID

after

string<date-time>

Filter sessions starting after this timestamp (ISO 8601, inclusive)

before

string<date-time>

Filter sessions starting before this timestamp (ISO 8601, inclusive)

minWastePercentage

number

Minimum waste percentage (0-100, inclusive)

Required range: 0 <= x <= 100

maxWastePercentage

number

Maximum waste percentage (0-100, inclusive)

Required range: 0 <= x <= 100

minWasteDurationInSeconds

number

Minimum waste duration in seconds (inclusive)

Required range: x >= 0

maxWasteDurationInSeconds

number

Maximum waste duration in seconds (inclusive)

Required range: x >= 0

insightTypes

string

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.

Example:

"Idling,AwayFromSeat"

insightGroups

string

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.

Example:

"StayFocused,DistractionFreeSpace"

enrichmentInsightTypes

string

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.

Example:

"ObservabilityCameraWorking,AcademicIntegrityStayInTheTest"

enrichmentInsightCategories

string

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.

Example:

"Observability,AcademicIntegrity"

isProctored

boolean

Filter by proctored status

webcamEnabled

boolean

Filter by webcam enabled status

enforcement

string

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.

Example:

"auto_stopped,warning_issued,notification_shown"

includeEnforcement

boolean

default:false

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.

limit

integer

default:20

Maximum number of items to return

Required range: 1 <= x <= 100

offset

integer

default:0

Number of items to skip

Required range: x >= 0

Response

Successful response with enriched sessions

Paginated list of enriched sessions

sessions

object[]

required

Array of enriched session objects

Show child attributes

offset

integer

required

Number of items skipped in the result set

limit

integer

required

Maximum number of items returned

total

integer

required

Total number of items available

⌘I