Ephemerals Tools

Inspect transient cached data produced by other tool calls.

Ephemerals are the working-memory view of DataGrout. When a tool returns a cache_ref, the underlying result stays available for short-term chaining. The Ephemerals suite helps you see what is currently cached and inspect a specific entry before deciding what to do next.

When entries expire, they disappear from the list. That is intentional. For durable storage, promote important outputs with deliverables.register.

ephemerals.list@1

List active cached datasets for the current user.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.list@1",
  "arguments": {
    "sort": "expiring_soon"
  }
}

Response:

{
  "ephemerals": [
    {
      "cache_ref": "rc_abc123",
      "label": "Overdue invoices (filtered)",
      "source_tool": "quickbooks@1/get-all-invoice-details-list@1",
      "record_count": 142,
      "type": "leaf",
      "created_seconds_ago": 120,
      "expires_in_seconds": 180
    }
  ],
  "total": 1,
  "message": "1 active cached dataset. Use cache_ref with Data, Frame, Math, or Prism tools."
}

Cost

0 credits — ETS scan only.

ephemerals.inspect@1

Inspect the schema, preview rows, and expiry details for a specific cached entry.

Parameters

Example

{
  "name": "data-grout@1/ephemerals.inspect@1",
  "arguments": {
    "cache_ref": "rc_abc123",
    "preview_rows": 5
  }
}

Response:

{
  "cache_ref": "rc_abc123",
  "type": "leaf",
  "record_count": 142,
  "schema": [
    {"field": "amount", "type": "float"},
    {"field": "customer", "type": "string"},
    {"field": "due_date", "type": "string"}
  ],
  "preview": [
    {"amount": 1500.0, "customer": "Acme Corp", "due_date": "2026-02-01"},
    {"amount": 750.0, "customer": "Widget Inc", "due_date": "2026-01-15"}
  ],
  "expires_in_seconds": 180,
  "created_seconds_ago": 120,
  "source_tool": "quickbooks@1/get-all-invoice-details-list@1",
  "label": "Overdue invoices (filtered)",
  "source_chain": {"type": "leaf"}
}

Cost

0 credits — cache inspection only.

When to use which tool