Credits and Receipts

Every tool call has a cost. You see it before and after.

DataGrout 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.

How Credits Work

Each operation through DataGrout consumes credits. The cost depends on the type of operation:

  • A standard tool call costs a small fixed amount.
  • Operations that use the intelligence layer (discovery, planning, verification) cost more.
  • Output transformations (reshaping, chart generation) have their own costs.
  • Cached or reused results cost less than first-time execution.

Your plan determines how many credits you receive each month and the rate for purchasing additional credits.

Estimates Before Execution

When 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.

{
  "plan": {
    "steps": [...],
    "estimated_credits": 12,
    "breakdown": {
      "discovery": 2,
      "step_1": 4,
      "step_2": 4,
      "step_3": 2
    }
  }
}

Budget limits can be set so that plans exceeding a threshold are rejected before any tool runs.

Receipts After Execution

Every completed tool call produces a receipt. The receipt captures what happened and what it cost.

Receipt Fields

Field Description
receipt_id Unique identifier for this receipt
timestamp When the operation completed
estimated_credits The pre-execution estimate
actual_credits The real cost after execution
net_credits Credits deducted from your balance
savings Difference between estimate and actual (if lower)
balance_before Your credit balance before this operation
balance_after Your credit balance after this operation
breakdown Per-component cost breakdown
byok BYOK discount applied (if any)

Example Receipt

{
  "receipt_id": "rcp_a1b2c3d4",
  "timestamp": "2026-02-26T14:30:00Z",
  "estimated_credits": 4,
  "actual_credits": 3,
  "net_credits": 3,
  "savings": 1,
  "balance_before": 9415,
  "balance_after": 9412,
  "breakdown": {
    "discovery": 0,
    "execution": 2,
    "intelligence": 1
  },
  "byok": {
    "discount_applied": true,
    "rate": 0.5
  }
}

Bring Your Own Key (BYOK)

When 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.

BYOK discounts are reflected in the byok section of each receipt. The discount rate depends on the integration.

Budget Controls

Set a maximum credit budget per operation, per session, or per billing period.

  • Per-operation: The planner rejects any plan that exceeds the specified limit.
  • Per-session: Cumulative spend across multiple calls within a session is capped.
  • Per-period: Monthly budget limits prevent runaway costs.

When a limit is reached, the system returns a clear error explaining which limit was hit and the current balance.

Where to See Credits

DataGrout UI

Your current balance appears in the header. Click it to view recent receipts and purchase additional credits.

Tool Call Responses

Every 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.

{
  "result": { "...tool output..." },
  "_meta": {
    "datagrout": {
      "receipt": {
        "receipt_id": "rcp_a1b2c3d4",
        "actual_credits": 3,
        "net_credits": 3,
        "balance_after": 9412
      },
      "execution_summary": "Completed. Cost: 3 credits (1 saved). Balance: 9412."
    }
  }
}

Conduit SDK

Use extract_meta() to pull the receipt from any tool call result.

result = await client.call_tool("salesforce@1/get_leads@1", {"limit": 10})
meta = extract_meta(result)

print(meta.receipt.net_credits)
print(meta.receipt.balance_after)

TypeScript

import { extractMeta } from '@datagrout/conduit';

const result = await client.callTool('salesforce@1/get_leads@1', { limit: 10 });
const meta = extractMeta(result);

if (meta) {
    console.log(meta.receipt.netCredits);
    console.log(meta.receipt.balanceAfter);
}

See Conduit SDK for setup.

Related