{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Ephemerals Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/ephemerals-tools",
  "summary": "Inspect transient cached data produced by other tool calls.",
  "content_markdown": "# Ephemerals Tools\n\nInspect transient cached data produced by other tool calls.\n\nEphemerals 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.\n\nWhen entries expire, they disappear from the list. That is intentional. For durable storage, promote important outputs with `deliverables.register`.\n\n---\n\n## `ephemerals.list@1`\n\nList active cached datasets for the current user.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `sort` | string | no | `\"newest\"` | Sort order: `\"newest\"`, `\"expiring_soon\"`, `\"largest\"` |\n| `limit` | integer | no | 20 | Max entries to return (max 100) |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/ephemerals.list@1\",\n  \"arguments\": {\n    \"sort\": \"expiring_soon\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"ephemerals\": [\n    {\n      \"cache_ref\": \"rc_abc123\",\n      \"label\": \"Overdue invoices (filtered)\",\n      \"source_tool\": \"quickbooks@1/get-all-invoice-details-list@1\",\n      \"record_count\": 142,\n      \"type\": \"leaf\",\n      \"created_seconds_ago\": 120,\n      \"expires_in_seconds\": 180\n    }\n  ],\n  \"total\": 1,\n  \"message\": \"1 active cached dataset. Use cache_ref with Data, Frame, Math, or Prism tools.\"\n}\n```\n\n### Cost\n\n0 credits — ETS scan only.\n\n---\n\n## `ephemerals.inspect@1`\n\nInspect the schema, preview rows, and expiry details for a specific cached entry.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `cache_ref` | string | yes | -- | The cache reference to inspect |\n| `preview_rows` | integer | no | 3 | Number of sample rows to include |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/ephemerals.inspect@1\",\n  \"arguments\": {\n    \"cache_ref\": \"rc_abc123\",\n    \"preview_rows\": 5\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"cache_ref\": \"rc_abc123\",\n  \"type\": \"leaf\",\n  \"record_count\": 142,\n  \"schema\": [\n    {\"field\": \"amount\", \"type\": \"float\"},\n    {\"field\": \"customer\", \"type\": \"string\"},\n    {\"field\": \"due_date\", \"type\": \"string\"}\n  ],\n  \"preview\": [\n    {\"amount\": 1500.0, \"customer\": \"Acme Corp\", \"due_date\": \"2026-02-01\"},\n    {\"amount\": 750.0, \"customer\": \"Widget Inc\", \"due_date\": \"2026-01-15\"}\n  ],\n  \"expires_in_seconds\": 180,\n  \"created_seconds_ago\": 120,\n  \"source_tool\": \"quickbooks@1/get-all-invoice-details-list@1\",\n  \"label\": \"Overdue invoices (filtered)\",\n  \"source_chain\": {\"type\": \"leaf\"}\n}\n```\n\n### Cost\n\n0 credits — cache inspection only.\n\n---\n\n## When to use which tool\n\n| Situation | Tool |\n|-----------|------|\n| See what data you have cached right now | `list` |\n| Preview the contents and schema of a cached entry | `inspect` |\n| Promote cached data to permanent storage | `deliverables.register` |\n"
}