n8n-nodes-gemini-token-telemetry

A drop-in replacement for n8n's Google Gemini Chat Model node that reports the token
usage the default node throws away — most importantly how much of your input came from
Gemini's context cache, which is billed at a fraction of the normal input rate.

If you run a long system prompt through an n8n AI Agent, cached input is probably the
single largest factor in your bill, and today it is invisible.

The problem

Google's API returns ten usage fields per call. Three reach your execution data. Two
independent layers drop the rest:

1. LangChain flattens it. @langchain/google-genai keeps the rich data on the message
(generations[0].message.usage_metadata, including input_token_details.cache_read) but
builds llmOutput.tokenUsage with only three fields:

llmOutput: { tokenUsage: {
  promptTokens:     usageMetadata.input_tokens,
  completionTokens: usageMetadata.output_tokens,
  totalTokens:      usageMetadata.total_tokens,
} }

2. n8n deletes the message. N8nLlmTracing.handleLLMEnd runs
pick(g, ['text','generationInfo']) over the generations — dropping message, and with it
usage_metadata. Crucially this happens before tokensUsageParser is called, so a custom
parser alone cannot recover anything.

This is not Gemini-specific. n8n's own Anthropic parser reads only input_tokens /
output_tokens and ignores cache_read_input_tokens, which Anthropic does return.

What this node does

It subclasses the chat model and enriches llmOutput.tokenUsage inside _generate, before
any callback exists — so it does not depend on callback ordering, which is not guaranteed.
A matching tokensUsageParser then copies the extra fields into the persisted output.

No patching of n8n. No patching of LangChain. Only two options n8n already accepts per node.

Fields added to tokenUsage

Two deliberate deviations

Reasoning is derived, not reported. Google's thoughtsTokenCount is not mapped by
LangChain into any field — but totalTokenCount includes it, so
reasoning = total - input - visible output. reasoningDerived: true marks that this was
arithmetic, not a provider field.

completionTokens becomes billable output (visible + reasoning), with the original
value preserved in outputTokensVisible. Two reasons: it is the correct number for cost,
and it prevents total data loss — n8n only persists real usage
if (tokenUsage.completionTokens > 0). When Google omits candidatesTokenCount the default
behaviour is to discard the real numbers and silently store a tiktoken estimate instead.

Measured

Against a 19,691-token stable prefix, second call (warm cache):

default node    { promptTokens: 19691, completionTokens: 1, totalTokens: 19692 }

this node       { promptTokens: 19691, completionTokens: 489, totalTokens: 20180,
                  cacheReadTokens: 16357, inputTokensTotal: 19691,
                  inputTokensBillable: 3334, cacheHitRatio: 0.8307,
                  outputTokensVisible: 1, reasoningTokens: 488,
                  reasoningDerived: true, outputTokensBillable: 489,
                  usageSource: "gemini-token-telemetry-v1" }

83% of the input was cached and previously invisible. Verified working inside an AI Agent
with tool calling, not only in a basic chain.

Cost (optional)

n8n already has a first-class cost slot: its default parser reads
tokenUsage.cost ?? tokenUsage.totalCost and propagates it to the tracing attribute
llm.cost.total. No provider fills it — the only occurrence of totalCost in the n8n codebase
is the line that reads it. This node fills it.

Prices come pre-filled. The package ships a built-in table for the Gemini models, copied
from the official pricing page, and each model
carries validity windows — so a promotional price switches over on its own date instead of
quietly becoming wrong:

Every cost row carries costPricingSource: builtin:<date the table was copied> or
node-parameters when you override. The number always says where it came from and how old
it is — that is the whole point of shipping a table instead of a constant.

Override by setting the three prices in the node's Options (per 1M tokens); yours win.
A model that is not in the table and has no prices set emits no cost field at all — an
absent number beats a zero that looks like a result.

⚠️ There is no pricing API. GET /v1beta/models returns twelve fields and none of them is a
price (measured: 53 models, zero price fields), and the Cloud Billing catalog rejects API keys
outright. So the table is a copy, and it has a date on it.

⚠️ Standard tier only. Batch is roughly half, Flex and Priority differ. The API does report
serviceTier in usageMetadata, but LangChain drops it before it reaches the node, so it
cannot be detected — Standard is assumed.

⚠️ The cache figure is the read price. Explicit caching also bills storage per hour,
which is not derivable from token counts. Implicit caching — what you get by default — has no
storage charge.

If you leave the cached-input price at 0, cached tokens are charged at the full input
price. That errs upward on purpose, and costCacheSavings then reports 0 rather than
inventing a discount.

Measured on two consecutive calls with the same prompt, at 0.30 / 0.075 / 2.50 USD per 1M:

cold cache   cost 0.00712980   cacheReadTokens      0   savings 0
warm cache   cost 0.00349698   cacheReadTokens 16357   savings 0.00368033

The cache halved the cost of an identical call. That is the number the default node cannot show.

The Model field starts empty — on purpose

n8n's frontend strips any parameter whose value equals the node's declared default before
sending it. With a "helpful" default like models/gemini-3.6-flash, anyone picking that exact
model has their choice silently erased on save. The node keeps working — off the default — and
nobody can answer "which model is running?" by looking at the workflow.

That is not hypothetical: it happened in production here, on the node serving 100% of traffic,
and the detector meant to catch it was blind because it matched on the old node type.

With default: "", no legitimate choice can collide with the default, so every choice is stored.
Leaving it empty raises a clear error naming the fix, instead of calling the API with no model
and letting the provider return something confusing.

What's new

0.5.0 — the Model field no longer has a default, so the UI can never erase your choice.
0.4.0 — built-in Gemini price table with validity windows; cost now works out of the box.
0.3.0 — optional cost calculation from user-supplied prices.
0.2.0 — model list is now loaded from the Google API instead of a free-text field.
0.1.1 — added a node icon.

Install

n8n → Settings → Community nodes → Install → n8n-nodes-gemini-token-telemetry

Requires N8N_COMMUNITY_PACKAGES_ENABLED=true. In queue mode, also set
N8N_REINSTALL_MISSING_PACKAGES=true so workers reinstall the package on boot when their
filesystem is ephemeral.

Use the existing Google Gemini(PaLM) API credential. Then point your Agent or Chain at
this node instead of the built-in Gemini model node.

Limitations

• Only the non-streaming path (_generate) is instrumented. Streaming is untested.
• reasoningTokens is derived; if Google ever stops including thinking in
  totalTokenCount, it will read zero rather than wrong — but verify before relying on it.
• The model list is a plain text field, not the dynamic dropdown of the built-in node.
• Tested against n8n 2.32.7 and @langchain/google-genai 2.1.24.

License

MIT