Insights & Reports

Insights endpoints cover three things:

1. Reports — daily / weekly / monthly write-ups. Both the v2.1 path (/v1/insights/report/*) and the v3.0 path (/v1/score_v3/report/*) live here.
2. Session summaries and highlights — LLM-generated titles, summaries, and notable sessions.
3. Daily summary — a single rolled-up summary for one calendar day.

v2.1 vs v3.0 reports

The shapes are nearly identical — only the data source differs. Use /v1/insights/report/* for v2.1-scored reports and /v1/score_v3/report/* for v3.0-scored reports. Both are documented below; the v3 family is grouped at the end of the Reports section.

GET /v1/insights/report

Get the latest insights report.

GET /v1/insights/report?scope=personal
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
scope	string	personal	Report scope
from	ISO8601	—	Start time
to	ISO8601	—	End time

Returns the most recent generated report as a JSON payload.

POST /v1/insights/report/generate

Generate a new insights report on demand. Runs synchronously and returns the full report payload in the response — there is no job ID.

POST /v1/insights/report/generate?scope=personal
Authorization: Bearer gck_your_key
Accept-Language: en

Parameter	Type	Default	Description
scope	string	personal	Report scope tag (see note below)
from	ISO8601	—	Start time
to	ISO8601	—	End time

The Accept-Language header (default en) selects the report’s output language.

Note on scope: The engine treats scope as an arbitrary tag persisted alongside the report row. It isn’t validated against a fixed enum; personal is the common default. Use whatever grouping tags your dashboard expects.

GET /v1/insights/report/pending

Fetch the most recent in-progress report (if any) for the org so the dashboard can resume polling across page reloads.

GET /v1/insights/report/pending
Authorization: Bearer gck_your_key

Returns the pending report record, or 204 No Content if none is running.

GET /v1/insights/report/status/:id

Status of a running generation — used with /generate calls that the client polls rather than blocks on.

GET /v1/insights/report/status/abc123
Authorization: Bearer gck_your_key

POST /v1/insights/report/cancel/:id

Cancel an in-progress generation. Idempotent; returns the final status.

POST /v1/insights/report/cancel/abc123
Authorization: Bearer gck_your_key

DELETE /v1/insights/report/:id

Delete a previously generated report.

DELETE /v1/insights/report/abc123
Authorization: Bearer gck_your_key

GET /v1/insights/report/history

Get report generation history.

GET /v1/insights/report/history?scope=personal&limit=20
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
scope	string	personal	Report scope
limit	integer	20	Max records

GET /v1/insights/report/:id

Get a specific report by ID.

GET /v1/insights/report/abc123
Authorization: Bearer gck_your_key

v3.0 reports

Same shape as the v2.1 report endpoints above, but scoped to PRISM Score v3.0 data. Use these for new integrations.

Endpoint	Method	Purpose
/v1/score_v3/report	GET	Latest v3 report (accepts the same scope / from / to params)
/v1/score_v3/report/generate	POST	Generate a v3 report synchronously; Accept-Language selects output language
/v1/score_v3/report/pending	GET	Most recent in-progress v3 report, or 204 No Content
/v1/score_v3/report/status/:id	GET	Status of a running v3 generation
/v1/score_v3/report/cancel/:id	POST	Cancel a running v3 generation
/v1/score_v3/report/history	GET	Past v3 reports (scope, limit)
/v1/score_v3/report/:id	GET / DELETE	Fetch or delete one v3 report

GET /v1/insights/sessions/stats

Session type statistics for a time range.

GET /v1/insights/sessions/stats?from=2024-01-01T00:00:00Z&to=2024-01-31T00:00:00Z
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
from	ISO8601	30 days ago	Start time
to	ISO8601	now	End time

GET /v1/insights/sessions/highlights

Session highlights — notable sessions based on scoring, patterns, or anomalies.

GET /v1/insights/sessions/highlights?from=2024-01-01T00:00:00Z&to=2024-01-31T00:00:00Z
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
from	ISO8601	30 days ago	Start time
to	ISO8601	now	End time

Response: a SessionHighlights object (returned directly, not wrapped).

GET /v1/insights/sessions/summary

Fetch the stored summary for a single session.

GET /v1/insights/sessions/summary?session_id=abc123
Authorization: Bearer gck_your_key

Parameter	Type	Required	Description
session_id	string	yes	Session to fetch the summary for

Returns 400 Bad Request if no summary exists for the session.

GET /v1/insights/sessions/summaries

List session summaries for the org, optionally filtered by developer.

GET /v1/insights/sessions/summaries?from=2024-01-01T00:00:00Z&limit=50
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
from	ISO8601	30 days ago	Start time
to	ISO8601	now	End time
user_id	UUID	—	Filter to a single developer
limit	integer	50	Max records
offset	integer	0	Pagination offset

Response: { "summaries": [...] }.

GET /v1/insights/sessions/details

Fetch detailed session data (turn-level metrics, tool activity, scores) for a single session.

GET /v1/insights/sessions/details?session_id=abc123
Authorization: Bearer gck_your_key

Parameter	Type	Required	Description
session_id	string	yes	Session to fetch details for

Response shape notes

• /report/history → { "reports": [...] }
• /sessions/stats → { "stats": [...] }
• /sessions/summaries → { "summaries": [...] }
• /sessions/highlights → SessionHighlights (unwrapped)
• /report and /report/:id → the generated report JSON (unwrapped)