---
title: "Overflow contents"
description: "Contents view of the offload S3 bucket per pattern, shows what's accumulating in the overflow queue, how fast it's growing, and routes to retriever_query for rehydration."
icon: material/bucket-outline
---

The maintenance-phase tool for the overflow bucket. It:

- queries `all_events_summaryBytes_total{routeState="drop"}` grouped by (pattern, service, container)
- joins the result to the cap-CSV so only `offload`-action patterns surface (not `drop` or `compact`)
- computes growth rate per pattern as the percent change between the first and second halves of the window

This tool does NOT scan S3 and does NOT estimate dollar savings. The overflow queue has negligible storage cost. Use [log10x_retriever_query](retriever-query.md) to fetch events back from the bucket.

## :material-code-braces: Example

!!! tenx-ask "You"

    what's in the overflow bucket this month?

!!! tenx-answer "Log10x"

    Overflow contents (30d): 3 patterns · 12.4 GB total · top grower +18%/week.

    | Pattern | Service | Bytes (30d) | Growth |
    |---|---|---:|---:|
    | cart_item_added_sku_$_qty_$ | checkout-svc | 5.2 GB | +18%/week |
    | healthcheck_ok_pod_$ | all | 4.1 GB | +2%/week |
    | debug_cache_miss_key_$ | cache-svc | 3.1 GB | −3%/week |

## :material-chat-question-outline: More to ask

- *"overflow contents, last 7 days"*
- *"overflow contents scoped to payment-svc"*
- *"fetch back the cart_item_added events from last week"* → routes to log10x_retriever_query

## :material-check-decagram-outline: Prerequisites

Retriever (S3 overflow bucket) and Receiver deployed. `log10x_configure_engine` run with at least one pattern assigned action=offload.

## :material-code-json: Schema and samples

??? tenx-input-schema "Input schema"

    Agent-facing JSON Schema (the canonical shape the MCP server publishes via `tools/list`):

    ```json
    {
      "type": "object",
      "properties": {
        "timeRange": {
          "type": "string",
          "enum": [
            "15m",
            "1h",
            "6h",
            "24h",
            "1d",
            "7d",
            "30d"
          ],
          "default": "30d",
          "description": "Window over which to compute overflow contents. 30d matches the maintenance-loop cadence; sub-30d windows for incident-window probes. '24h' and '1d' are equivalent."
        },
        "service": {
          "type": "string",
          "description": "Filter to a single service. Omit for the full overflow queue across every service that routes to S3."
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500,
          "default": 50,
          "description": "Cap on the number of per-pattern rows returned. Total bytes always reflect the full overflow, even when rows are truncated."
        },
        "environment": {
          "type": "string",
          "description": "Environment nickname"
        },
        "view": {
          "type": "string",
          "const": "summary",
          "default": "summary",
          "description": "Output format. Always \"summary\", the typed envelope (data.patterns[], data.totals)."
        }
      },
      "additionalProperties": false
    }
    ```

    Source: [`src/tools/overflow-contents.ts`](https://github.com/log-10x/log10x-mcp/blob/main/src/tools/overflow-contents.ts).

??? tenx-output-schema "Output schema"

    The `data` block inside the [StructuredOutput envelope](../index.md#json-by-default-output):

    ```typescript
    interface ToolData {
      patterns: Array<{
        pattern_hash: string;
        service: string;
        container: string;
        bytes_in_window: number;
        event_count_in_window: number;
        time_window_first: string | null;
        time_window_last: string | null;
        time_window_basis: 'computed' | 'single_sample' | 'insufficient_samples';
        growth_rate_pct: number | null;
        growth_rate_basis: 'computed' | 'new_pattern' | 'insufficient_baseline';
        action: 'pass' | 'sample' | 'compact' | 'drop' | 'offload' | 'tier_down' | null;
        action_source: 'action_intent' | 'legacy_cap_csv' | 'unverified';
      }>;
      total_bytes_in_window: number;
      total_event_count_in_window: number;
      pattern_count: number;
      truncated: boolean;
      cap_csv_status: {
        kind: 'not_configured' | 'configured_not_loaded' | 'loaded' | 'lookup_failed';
        reason: string;
        source: string | null;
      };
      time_range: string;
    }
    ```

    Envelope-level fields: `summary.headline`, `actions[]` (routes to `log10x_retriever_query` for rehydration), `schema_epoch`.