ledger_write

Append a row to the D1 `run_ledger` — one call per AI invocation.

Category
Ledger
Stability
Stable
Version
v1
Auth
cf-access

Input schema

{
  "type": "object",
  "properties": {
    "surface": { "type": "string", "enum": ["openwebui", "paperclip", "email_autoreply", "mcp_tool", "skill", "other"] },
    "provider": { "type": "string", "enum": ["local_llamacpp", "anthropic", "other"] },
    "model": { "type": "string" },
    "tokens_in": { "type": "integer", "minimum": 0 },
    "tokens_out": { "type": "integer", "minimum": 0 },
    "latency_ms": { "type": "integer", "minimum": 0 },
    "cost_eur": { "type": "number", "minimum": 0 },
    "cost_eur_if_cloud": { "type": "number", "minimum": 0, "description": "Counterfactual — what this call would have cost on the cloud reference model." },
    "skill": { "type": "string" },
    "context": { "type": "object", "additionalProperties": true }
  },
  "required": ["surface", "provider", "model", "tokens_in", "tokens_out", "cost_eur", "cost_eur_if_cloud"]
}

Output schema

{
  "type": "object",
  "properties": {
    "row_id": { "type": "string" },
    "written_at": { "type": "string", "format": "date-time" }
  }
}

Example invocation

{
  "tool": "ledger_write",
  "arguments": {
    "surface": "skill",
    "provider": "local_llamacpp",
    "model": "qwen2.5-coder-32b",
    "tokens_in": 812,
    "tokens_out": 144,
    "latency_ms": 2100,
    "cost_eur": 0.0,
    "cost_eur_if_cloud": 0.0048,
    "skill": "summarize-email"
  }
}

Example response

{
  "row_id": "lrw_01JK3QZ9B3",
  "written_at": "2026-04-22T13:02:01Z"
}

Load-bearing for Principle 2 — the savings claim depends on this row existing for every AI run. Missing rows mean the savings dashboard can’t prove what it says.