{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Credits & Receipts",
  "chunked": true,
  "url": "https://library.datagrout.ai/credits-receipts",
  "summary": "**Every tool call has a cost. You see it before and after.**",
  "content_markdown": "# Credits and Receipts\n\n**Every tool call has a cost. You see it before and after.**\n\nDataGrout uses credits as the unit of cost for all operations. Before a tool executes, you get an estimate. After it executes, you get a receipt with the actual cost, a breakdown by component, and any savings applied. Budget controls prevent agents from exceeding spending limits.\n\n---\n\n## How Credits Work\n\nEach operation through DataGrout consumes credits. The cost depends on the type of operation:\n\n- A standard tool call costs a small fixed amount.\n- Operations that use the intelligence layer (discovery, planning, verification) cost more.\n- Output transformations (reshaping, chart generation) have their own costs.\n- Cached or reused results cost less than first-time execution.\n\nYour plan determines how many credits you receive each month and the rate for purchasing additional credits.\n\n---\n\n## Estimates Before Execution\n\nWhen you discover or plan a workflow, the response includes a credit estimate for each step and the total. Your agent can decide whether to proceed based on the projected cost.\n\n```json\n{\n  \"plan\": {\n    \"steps\": [...],\n    \"estimated_credits\": 12,\n    \"breakdown\": {\n      \"discovery\": 2,\n      \"step_1\": 4,\n      \"step_2\": 4,\n      \"step_3\": 2\n    }\n  }\n}\n```\n\nBudget limits can be set so that plans exceeding a threshold are rejected before any tool runs.\n\n---\n\n## Receipts After Execution\n\nEvery completed tool call produces a receipt. The receipt captures what happened and what it cost.\n\n### Receipt Fields\n\n| Field | Description |\n|-------|-------------|\n| `receipt_id` | Unique identifier for this receipt |\n| `timestamp` | When the operation completed |\n| `estimated_credits` | The pre-execution estimate |\n| `actual_credits` | The real cost after execution |\n| `net_credits` | Credits deducted from your balance |\n| `savings` | Difference between estimate and actual (if lower) |\n| `balance_before` | Your credit balance before this operation |\n| `balance_after` | Your credit balance after this operation |\n| `breakdown` | Per-component cost breakdown |\n| `byok` | BYOK discount applied (if any) |\n\n### Example Receipt\n\n```json\n{\n  \"receipt_id\": \"rcp_a1b2c3d4\",\n  \"timestamp\": \"2026-02-26T14:30:00Z\",\n  \"estimated_credits\": 4,\n  \"actual_credits\": 3,\n  \"net_credits\": 3,\n  \"savings\": 1,\n  \"balance_before\": 9415,\n  \"balance_after\": 9412,\n  \"breakdown\": {\n    \"discovery\": 0,\n    \"execution\": 2,\n    \"intelligence\": 1\n  },\n  \"byok\": {\n    \"discount_applied\": true,\n    \"rate\": 0.5\n  }\n}\n```\n\n---\n\n## Bring Your Own Key (BYOK)\n\nWhen you provide your own API keys for upstream services, DataGrout applies a discounted credit rate. You pay less because DataGrout is not proxying the upstream API cost on your behalf.\n\nBYOK discounts are reflected in the `byok` section of each receipt. The discount rate depends on the integration.\n\n---\n\n## Budget Controls\n\nSet a maximum credit budget per operation, per session, or per billing period.\n\n- **Per-operation**: The planner rejects any plan that exceeds the specified limit.\n- **Per-session**: Cumulative spend across multiple calls within a session is capped.\n- **Per-period**: Monthly budget limits prevent runaway costs.\n\nWhen a limit is reached, the system returns a clear error explaining which limit was hit and the current balance.\n\n---\n\n## Where to See Credits\n\n### DataGrout UI\n\nYour current balance appears in the header. Click it to view recent receipts and purchase additional credits.\n\n### Tool Call Responses\n\nEvery tool call response includes a `_meta.datagrout` object containing the receipt (and optionally cost estimate, CTC details, and execution summary). Receipt inclusion is controlled in your [Interaction Settings](interaction-settings).\n\n```json\n{\n  \"result\": { \"...tool output...\" },\n  \"_meta\": {\n    \"datagrout\": {\n      \"receipt\": {\n        \"receipt_id\": \"rcp_a1b2c3d4\",\n        \"actual_credits\": 3,\n        \"net_credits\": 3,\n        \"balance_after\": 9412\n      },\n      \"execution_summary\": \"Completed. Cost: 3 credits (1 saved). Balance: 9412.\"\n    }\n  }\n}\n```\n\n### Conduit SDK\n\nUse `extract_meta()` to pull the receipt from any tool call result.\n\n```python\nresult = await client.call_tool(\"salesforce@1/get_leads@1\", {\"limit\": 10})\nmeta = extract_meta(result)\n\nprint(meta.receipt.net_credits)\nprint(meta.receipt.balance_after)\n```\n\n**TypeScript**\n\n```typescript\nimport { extractMeta } from '@datagrout/conduit';\n\nconst result = await client.callTool('salesforce@1/get_leads@1', { limit: 10 });\nconst meta = extractMeta(result);\n\nif (meta) {\n    console.log(meta.receipt.netCredits);\n    console.log(meta.receipt.balanceAfter);\n}\n```\n\nSee [Conduit SDK](conduit-sdk) for setup.\n\n---\n\n## Related\n\n- [Conduit SDK](conduit-sdk) -- Extracting receipts programmatically\n- [Interaction Settings](interaction-settings) -- Configuring receipt inclusion in responses\n- [Core Concepts: Credits](core-concepts) -- Credit model overview\n- [Lab paper: Credit System](https://labs.datagrout.ai/papers/credits) -- Economic primitives for autonomous systems\n"
}