Insights Endpoints

Insights endpoints provide generated reports and session analysis.

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

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)