Query status
Inspect a previously-submitted Retriever query by ID. Reads the _DONE.json marker from S3, lists event files and byte-count markers, optionally fetches per-query CloudWatch events and pod logs, and runs a diagnostics engine that surfaces known dispatcher-failure signatures with a stored remedy. Call after log10x_retriever_query returns 0 events or partial_results=true to find out what actually happened inside the engine.
Example
You
why did my last retriever query return 0 events?
Log10x
Query 7f3c... completed in 240ms.
Submitted 48 scan tasks. Scanned 0 objects.
DIAGNOSTIC [CONFIRMED]: dispatcher_failure.
Matched pattern: include_resolve_streamer_legacy.
Remedy: upgrade chart to 1.0.21+.
More to ask
- "status of query
7f3c1d2e-..." - "diagnose the last retriever call, skip pod logs"
- "what's in
_DONE.jsonfor queryabc-123on targetapp"
Prerequisites
This tool requires the Retriever deployed with __SAVE_LOG10X_RETRIEVER_URL__ and __SAVE_LOG10X_RETRIEVER_BUCKET__ set. Pod-log confirmation also requires kubectl access from the MCP process; per-query CloudWatch events require queryLogGroup configured in helm values.
Schema and samples
Input example
Representative call (synthetic, not captured from the live demo env).
Input schema
Agent-facing JSON Schema (the canonical shape the MCP server publishes via tools/list):
{
"type": "object",
"properties": {
"query_id": {
"type": "string",
"description": "UUID of a previously-submitted retriever query. Returned as data.query_id from log10x_retriever_query."
},
"target": {
"type": "string",
"default": "app",
"description": "Target app/service prefix used when the original query was submitted. Defaults to \"app\". Must match the target that was passed to the original query."
},
"include_pod_logs": {
"type": "boolean",
"default": true,
"description": "When true and a dispatcher_failure is suspected (scanned=0 + submittedTasks>0), attempt kubectl logs on the retriever pod to confirm the chart 1.0.20 include-resolution error. Requires kubectl access from the MCP process. Set false to skip the kubectl call."
}
},
"required": [
"query_id"
],
"additionalProperties": false
}
Source: src/tools/retriever-query-status.ts.
Output example
Representative envelope (synthetic, not captured from the live demo env). view: "summary" returns the full StructuredOutput with typed data.
Headline (the 1-line agent-facing answer):
Retriever query status for 7f3c1d2e-...: Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0.
{
"schema_version": "1.0",
"schema_epoch": "2026-05-25",
"tool": "log10x_retriever_query_status",
"generated_at": "2026-06-05T12:00:00.000Z",
"view": "summary",
"summary": {
"headline": "Retriever query status for 7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f: Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0."
},
"data": {
"status": "done",
"query_id": "7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"target": "app",
"bucket": "log10x-retriever-archive",
"s3_done_key": "indexing-results/tenx/app/qr/7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f/_DONE.json",
"stats": {
"queryId": "7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"completedAt": "2026-06-05T11:59:58.120Z",
"elapsedMs": 240,
"reason": "dispatched",
"scanned": 0,
"matched": 0,
"skippedSearch": 0,
"skippedTemplate": 0,
"streamRequests": 0,
"streamBlobs": 0,
"submittedTasks": 48,
"expectedMarkers": 48
},
"done_read_error": null,
"marker_count": 0,
"event_files": {
"count": 0,
"total_bytes": 0,
"keys": []
},
"cloudwatch_events": {
"log_group": "/log10x/retriever/query",
"event_count": 4,
"events": [
{
"timestamp": "2026-06-05T11:59:57.880Z",
"level": "ERROR",
"message": "could not resolve include: 'cloud/streamer/subquery'",
"data": { "queryId": "7f3c1d2e-..." }
}
],
"error": null
},
"diagnostics": {
"category": "dispatcher_failure",
"confidence": "confirmed",
"evidence": [
"_DONE.json: reason=\"dispatched\", submittedTasks=48, streamRequests=0, scanned=0",
"CONFIRMED: pod logs match dispatcher pattern 'include_resolve_streamer_legacy'.",
"Remedy: Chart < 1.0.21 with legacy hardcoded streamer paths. Upgrade chart to 1.0.21+ which uses apps/retriever/* paths."
],
"pattern_id": "include_resolve_streamer_legacy",
"remedy": "Chart < 1.0.21 with legacy hardcoded streamer paths. Upgrade chart to 1.0.21+ which uses apps/retriever/* paths."
},
"human_summary": "Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0. No event JSONL files found in the qr/ prefix. 4 CloudWatch event(s) from log group /log10x/retriever/query. DIAGNOSTIC [CONFIRMED]: dispatcher_failure ...",
"source_disclosure": {
"retriever_state_source": "helm",
"namespace": "log10x"
}
},
"actions": [
{
"tool": "log10x_advise_retriever",
"args": {},
"reason": "chart 1.0.21+ upgrade or the rename-residual fix in modules/feat/soft-drop resolves this dispatcher failure"
}
],
"truncated": false,
"warnings": []
}
Output schema
The data block inside the StructuredOutput envelope:
interface ToolData {
status: 'done' | 'not_found' | 'unknown';
query_id: string;
target: string;
bucket: string;
s3_done_key: string;
stats: {
queryId?: string;
completedAt?: string;
elapsedMs?: number;
reason?: string;
scanned?: number;
matched?: number;
skippedSearch?: number;
skippedTemplate?: number;
streamRequests?: number;
streamBlobs?: number;
submittedTasks?: number;
expectedMarkers?: number;
} | null;
done_read_error?: string;
marker_count: number;
event_files: {
count: number;
total_bytes: number;
keys: string[];
};
cloudwatch_events: {
log_group: string | null;
event_count: number;
events: Array<{
timestamp: string;
level: string;
message: string;
data?: Record<string, unknown>;
}>;
error?: string;
advisory?: string;
};
diagnostics: {
category: 'dispatcher_failure' | 'results_not_uploaded' | 'dispatch_failure' | 'observability_disabled' | 'ok' | 'unknown';
confidence: 'confirmed' | 'suspected' | 'advisory' | 'none';
evidence: string[];
pattern_id?: 'include_resolve_streamer_legacy' | 'config_var_resolve' | 'launch_pipeline_run_fail';
remedy?: string;
};
human_summary: string;
source_disclosure: {
retriever_state_source: string;
namespace: string | null;
};
}
Envelope-level fields the agent should also read: summary.headline (1-line answer), actions[] (next-call chain hints as {tool, args, reason}), truncated: boolean, images[] (PNG attachments where applicable), schema_epoch (engine-ID stability boundary).