Sessions API — ADK

API reference for reading and managing ADK conversation sessions. For architecture and configuration, see ADK.

All paths are relative to the ADK service root (port 8103 locally) under /api/v1/adk. Authentication, required headers, and the error envelope follow the API conventions. X-Project-Id is optional and, when sent, must match the session's project for project-scoped reads.

Non-superusers only see their own sessions: list and read routes filter by the authenticated user.

Data Model

Session (SessionsList)

Event (EventsList): id, app_name, user_id, session_id, invocation_id, author, timestamp, branch, content, long_running_tool_ids_json, grounding_metadata, custom_metadata, usage_metadata, citation_metadata, partial, turn_complete, error_code, error_message, interrupted.

Endpoints

List Sessions

GET /api/v1/adk/sessions/

Returns an array of sessions. Test sessions appear only to their owner and are redacted: state is {"test_session_schema_version": 1}, metadata is empty, and test_session_title carries the test name (links replaced with [link]).

curl "http://localhost:8103/api/v1/adk/sessions/?agent_id=AGENT_ID&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID"

List Session Events

GET /api/v1/adk/sessions/{session_id}/events/?skip=0&limit=100

Returns events in chronological order. Test sessions return 403 with "Use the redacted test-session trace endpoint". Cosmos Assistant sessions (channel: cosmos_assistant) are readable only by their owner and only in the session's project.

Compact Session

POST /api/v1/adk/sessions/{session_id}/compact

Runs compaction immediately instead of waiting for the automatic threshold. Name the summarizing model through an agent or an explicit provider and model.

{"compacted": true, "events_compacted": 42, "start_timestamp": 1761700000.0, "end_timestamp": 1761703600.0, "reason": null}

When nothing is eligible, the response is {"compacted": false, "reason": "No events eligible for compaction"}. Returns 400 for an unusable model, 403 for test sessions, and 404 for unknown sessions.

Update Session Metadata

PATCH /api/v1/adk/sessions/{session_id}/metadata

Merges {"metadata": {...}} into the existing metadata and returns the updated session. Requires the adk.session.write permission. These keys are server-owned and return 422: analyzer_score, test_snapshot, test_feedback, test_turn_timings, test_output_pii, test_suggestions.

curl -X PATCH "http://localhost:8103/api/v1/adk/sessions/SESSION_ID/metadata" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"title": "Weather chat"}}'

Test-Session Endpoints

Test sessions are created from the AI Testing Workspace with a V2 start event that includes test_session (see Converse API). ADK stores an immutable test_snapshot in session metadata.

Access rules. The session owner can use every route. In a project-scoped test session, another user needs cosmos.project.read and observer.session_trace.review on the project to act as a reviewer. Service tokens must name a delegated user. A mismatched X-Project-Id returns 403; missing or inconsistent scope data returns 503.

Evaluation

Evaluation routes return 503 unless ADK_TEST_EVALUATE_ENABLED=true.

• POST .../evaluate requires adk.analyzer.run and an agent version with an attached analyzer (analyzer_id and analyzer_version); otherwise it returns 422. It returns 201 with {session_id, quality_run_id, status}.
• GET .../evaluations/ returns up to 20 runs as {session_id, runs: [{quality_run_id, status, created_at}], has_more}.
• GET .../evaluations/{run_id} returns {session_id, quality_run_id, status, metrics_schema_version, metrics}, combining the analyzer result with turn timing, PII, and cost metrics.

Related Pages

• Converse API: conversation, streaming, and agent execution
• ADK: architecture, configuration, and troubleshooting