--- title: "Query" description: "Read back the offloaded cohort for a pattern from the customer-owned overflow bucket: the events the Receiver held back from the analyzer." icon: material/bucket-outline --- Read back the offloaded cohort for a pattern: the events the [Receiver](../../../receiver/) diverted from the analyzer under an `offload` action and routed to the customer-owned S3 overflow bucket. These are the down-tiered or dropped events the log analyzer never received, fetched byte-range-scoped by pattern name or Bloom-filter search via the [Retriever](../../../retriever/). The bucket stays in the customer account; 10x reads it in place. Re-ingest is customer-driven, not an MCP action. This is not a mirror of what the analyzer holds. It surfaces only the cohort the Receiver held back. Use it to: - inspect an offload decision - pull the held-back events during an incident - sample what was diverted for an audit ## :material-code-braces: Example !!! tenx-ask "You" sample the offloaded `payment_retry` events for `acme-corp` !!! tenx-answer "Log10x" 412 events match the tenant filter, read back from the overflow bucket in 1.8s. Sample: ``` 2026-06-02T14:32:11Z payment_retry_attempt customer_id=acme-corp-inc attempt=3 reason=timeout 2026-06-02T14:32:14Z payment_retry_attempt customer_id=acme-corp-inc attempt=4 reason=timeout ... ``` This pattern is in the Receiver's offload cohort and these events landed in the bucket. The full match set is the `*.jsonl` objects under the results prefix; point a loader at it to re-ingest. ## :material-chat-question-outline: More to ask - *"sample the held-back `ECONNREFUSED` events from last night's incident"* - *"verify the offload decision for `Payment_Gateway_Timeout` filtered to payment-svc"* - *"pull the offloaded `Auth_Failed` events for the audit, raw"* ## :material-check-decagram-outline: Prerequisites This tool requires the [Retriever](../../../retriever/) deployed against the overflow bucket. Set `LOG10X_RETRIEVER_LOG_GROUP` to enable the diagnostics line below the execution summary; without it, the response carries `pollingError` instead. When the Retriever is absent, the tool returns a typed `not_configured` envelope whose remediation points the agent at the Retriever deploy (not the metrics backend). ## :material-code-json: Schema and samples ??? tenx-input-example "Input example" Real call against the demo env (captured by [`scripts/capture-tool-envelopes.mjs`](https://github.com/log-10x/log10x-mcp/blob/main/scripts/capture-tool-envelopes.mjs)). ```json { "pattern": "open_telemetry_opensearchexporter_clientLogger_LogRoundTrip_open_telemetry_opensearchexporter_v_go_github_opensearch_project", "from": "now-15m", "to": "now", "limit": 3, "view": "summary" } ``` ??? tenx-input-schema "Input schema" Agent-facing JSON Schema (the canonical shape the MCP server publishes via `tools/list`): ```json { "type": "object", "properties": { "pattern": { "type": "string", "description": "Reporter-named pattern (Symbol Message) to scope the scan to. Auto-translated to `tenx_user_pattern == \"\"` Bloom-filter expression. Use this when the agent has a pattern name from event_lookup / top_patterns / cost_drivers and wants the offloaded events for it without authoring the Bloom expression by hand. Mutually exclusive with `search`; if both are provided, `search` wins and `pattern` is ignored. Example: `pattern: \"Payment_Gateway_Timeout\"`." }, "pattern_hash": { "type": "string", "description": "Canonical pattern_hash from top_patterns / event_lookup. When provided, search is auto-built as `tenx_hash == \"\"` and no name resolution runs. This is the chain-stable identity emitted by top_patterns.payload.patterns[].pattern_hash. Bypasses the name→hash resolver entirely. Precedence: `search` > `pattern_hash` > `pattern`. Example: `pattern_hash: \"4Kjc7PHLWqY\"`." }, "search": { "type": "string", "description": "Bloom-filter search expression using the TenX subset: `==`, `||`, `&&`, `includes(field, \"substr\")`. Example: `severity_level==\"ERROR\" && includes(text, \"ECONNREFUSED\")`. Selective values are dramatically cheaper than open-ended scans. Omit to scan the full window (bounded by limit/processingTime). Pass `pattern` instead for the common case of scoping to one Reporter-named pattern." }, "from": { "type": "string", "description": "Start of the query window. Accepts ISO8601 (`2026-01-15T00:00:00Z`), epoch millis, or relative (`now-1h`, `now-24h`, `now-7d`). Normalized to the engine's `now(\"-1h\")` form before dispatch." }, "to": { "type": "string", "default": "now", "description": "End of the query window. Same grammar as `from`. Default `now`." }, "filters": { "type": "array", "items": { "type": "string" }, "description": "JavaScript filter expressions evaluated in-memory against each decoded event after the Bloom-scoped fetch. Full TenX JS API: `this.customer_id === \"acme-corp\"`, `this.http_code.startsWith(\"5\")`. Filters are AND-combined." }, "target": { "type": "string", "description": "Target app/service prefix to scope the index scan. Defaults to __SAVE_LOG10X_RETRIEVER_TARGET__ (env var). Required if no default is configured." }, "limit": { "type": "number", "minimum": 1, "maximum": 10000, "default": 500, "description": "Hard cap on events returned after merging per-worker result files. Default 500. Typical conversational queries want 10-100; the LLM will render only the first 50." }, "format": { "type": "string", "enum": [ "events", "count", "aggregated", "ephemeral_series" ], "default": "events", "description": "`events` (default: raw events), `count` (total + severity/service rollups, no event bodies), `aggregated` (events bucketed into a time series, use with bucket_size), `ephemeral_series` (bucketed series in Prometheus range-query shape for cross-pillar correlation). All four formats are rolled up client-side from the same events stream." }, "bucket_size": { "type": "string", "default": "5m", "description": "Bucket size when format=aggregated or ephemeral_series. Examples: `1m`, `5m`, `1h`, `1d`." }, "environment": { "type": "string", "description": "Environment nickname, required if multi-env." }, "view": { "type": "string", "const": "summary", "default": "summary", "description": "summary returns the typed envelope (data.events_matched, data.events[], data.query_id, data.diagnostics, data.human_summary). The deprecated markdown view was removed; data.human_summary carries the prose distillation for chat rendering." } }, "required": [ "from" ], "additionalProperties": false } ``` Source: [`src/tools/retriever-query.ts`](https://github.com/log-10x/log10x-mcp/blob/main/src/tools/retriever-query.ts). ??? tenx-output-example "Output example" Real envelope from the demo env. `view: "summary"` returns the full `StructuredOutput` with typed `data`. Long arrays + base64 PNG bodies trimmed for readability; the real call returns them in full. Headline (the 1-line agent-facing answer): > _`log10x_retriever_query` ran but its retriever precondition is not configured. This is an expected state, not a failure: read data.payload.remediation, surface the fix, and continue the chain without this tool._ ```json { "schema_version": "1.0", "schema_epoch": "2026-05-25", "tool": "log10x_retriever_query", "generated_at": "2026-06-08T15:38:35.777Z", "view": "summary", "summary": { "headline": "`log10x_retriever_query` ran but its retriever precondition is not configured. This is an expected state, not a failure: read data.payload.remediation, surface the fix, and continue the chain without this tool." }, "data": { "status": "not_configured", "precondition": "retriever", "remediation": "## Retriever not configured\n..." }, "actions": [], "truncated": false, "warnings": [] } ``` ??? tenx-output-schema "Output schema" The `data` block inside the [StructuredOutput envelope](../index.md#json-by-default-output) on a configured run: ```typescript interface ToolData { status: string; from: string; to: string; filters: unknown[]; format: string; events_matched: number; events_returned: number; worker_files: number; wall_time_ms: number; truncated: boolean; partial_results: boolean; // Where the full match set lives in S3: one *.jsonl per worker. // Point a loader at this prefix to re-ingest. Customer-driven, in the customer account. results_location?: { bucket: string; prefix: string; uri: string }; events_preview: unknown[]; } ``` 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).