Thinking Endpoints
The thinking API provides RBAC-protected endpoints for accessing agent thinking traces, individual steps, LLM metrics, API call records, and similarity-based trace search.
Base Path
/api/v1/context-graph/thinking/Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /thinking/:trace_id | Get a thinking trace (RBAC-filtered) |
| GET | /thinking/:trace_id/steps | Get thinking steps for a trace |
| GET | /thinking/:trace_id/metrics | Get LLM metrics for a trace |
| GET | /thinking/:trace_id/api-calls | Get API call records for a trace |
| POST | /thinking/search | Search thinking traces by similarity |
| POST | /thinking/compare | Compare two thinking traces |
GET /thinking/:trace_id
Returns a single thinking trace, filtered by the user's RBAC visibility level.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
trace_id | string | Unique trace identifier |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
tenant_id | string | Yes | Tenant identifier |
include_steps | boolean | No | Include thinking steps (default: false) |
include_api_calls | boolean | No | Include API call records (default: false) |
Response (DETAILED visibility)
{
"trace_id": "trace-123",
"tenant_id": "acme",
"session_id": "sess-456",
"actor_urn": "urn:matih:agent:acme:bi-agent",
"goal": "Show me total sales by region",
"status": "completed",
"outcome": "success",
"started_at": "2025-06-15T10:30:00Z",
"completed_at": "2025-06-15T10:30:03Z",
"step_count": 4,
"api_call_count": 2,
"total_duration_ms": 3200.5,
"total_cost_usd": 0.045,
"total_input_tokens": 1500,
"total_output_tokens": 500,
"total_thinking_tokens": 800,
"model_ids_used": ["gpt-4"],
"path_taken": ["INTENT_ANALYSIS", "SQL_GENERATION", "VALIDATION", "RESPONSE"],
"avg_confidence": 0.91,
"steps": null,
"api_calls": null
}GET /thinking/:trace_id/steps
Returns the individual thinking steps for a trace.
Response
{
"trace_id": "trace-123",
"steps": [
{
"step_id": "step-1",
"step_type": "INTENT_ANALYSIS",
"sequence_number": 1,
"reasoning": "User wants aggregated sales data grouped by region",
"confidence": 0.95,
"duration_ms": 450.0,
"model_id": "gpt-4",
"input_tokens": 150,
"output_tokens": 50
}
],
"total_steps": 4
}POST /thinking/search
Search thinking traces by text similarity.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query_text | string | Yes | Text to search for (max 500 characters) |
tenant_id | string | Yes | Tenant identifier |
top_k | integer | No | Number of results (default: 10, max: 50) |
min_similarity | float | No | Minimum similarity score |
embedding_type | string | No | input, output, thinking (default: input) |
outcome_filter | string | No | Filter by outcome: success, failure |
Response
{
"results": [
{
"trace_id": "trace-789",
"similarity_score": 0.92,
"goal": "Display total revenue by product category",
"path_taken": ["INTENT_ANALYSIS", "SQL_GENERATION", "VALIDATION"],
"outcome": "success"
}
],
"total_results": 5,
"query_time_ms": 85.3
}POST /thinking/compare
Compare two thinking traces side by side.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
trace_id_a | string | Yes | First trace ID |
trace_id_b | string | Yes | Second trace ID |
tenant_id | string | Yes | Tenant identifier |
Response
{
"trace_a": { "trace_id": "trace-1", "path_taken": [...] },
"trace_b": { "trace_id": "trace-2", "path_taken": [...] },
"similarity_score": 0.78,
"path_overlap": 0.66,
"common_steps": ["INTENT_ANALYSIS", "SQL_GENERATION"],
"divergence_point": "VALIDATION"
}Required Permissions
| Endpoint | Minimum Permission |
|---|---|
| Get Trace | context_graph:traces:read |
| Get Steps | context_graph:thinking:read |
| Get Metrics | context_graph:metrics:read |
| Get API Calls | context_graph:thinking:read |
| Search | context_graph:traces:read |
| Compare | context_graph:thinking:read |