Query
Read back the offloaded cohort for a pattern: the events the Receiver diverted from the SIEM 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. 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 SIEM 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, or sample what was diverted for an audit.
Example
You
sample the offloaded payment_retry events for acme-corp
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.
More to ask
- "sample the held-back
ECONNREFUSEDevents from last night's incident" - "verify the offload decision for
Payment_Gateway_Timeoutfiltered to payment-svc" - "pull the offloaded
Auth_Failedevents for the audit, raw"
Prerequisites
This tool requires the 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).
Schema and samples
Input example
Real call against the demo env (captured by scripts/capture-tool-envelopes.mjs).
Input schema
Agent-facing JSON Schema (the canonical shape the MCP server publishes via tools/list):
{
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "Reporter-named pattern (Symbol Message) to scope the scan to. Auto-translated to `tenx_user_pattern == \"<name>\"` 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 == \"<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.
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_queryran 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.
{
"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": []
}
Output schema
The data block inside the StructuredOutput envelope on a configured run:
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).