TokenCalculator for Activepieces

Measure the exact workload assembled by an Activepieces flow before sending it to an LLM. The piece accepts mapped text, repeatable file inputs, and supported images, then returns token, cost, and context-window fields that can drive later branches.

What does the Activepieces Token Calculator piece do?

Token Calculator is a community Activepieces piece for LLM token counting and model-cost estimation. It creates a reusable preflight step between content collection and an AI action, helping flows avoid context-limit failures, compare model prices, enforce per-request budgets, and record which uploaded files were included.

Install the community piece

1. Open your Activepieces instance and go to Settings → My Pieces.
2. Select Install Piece.
3. Enter @jay0073/piece-tokencalculator and install the latest version.
4. Create or reopen a flow, add a step, and search for Token Calculator.

Use version 0.1.1 or later. No connection or TokenCalculator API key is required. Community npm pieces must be enabled by the deployment administrator; if Install Piece is unavailable, ask the administrator to enable or install it.

Quick start: count mapped text

1. Create a trigger, such as Webhook, Schedule, or a form/app trigger that returns text.
2. Add Token Calculator → Count Tokens.
3. Click Text and map the prompt/message field from the trigger or an earlier step.
4. Leave Files empty, choose the target model, and test the step.

Use the data picker instead of manually guessing a template path. Activepieces inserts the correct reference for the selected trigger or step output.

Available actions

Count Tokens

Choose one model and measure combined text and files. Use this for a budget check or context-window guard without forecasting generated output.

Estimate Cost

Choose one model and provide Expected Output Tokens. Optionally enter Cached Input Tokens. The result separates normal input, cached input, output, and total USD cost.

Compare Models

Select two or more models and enter expected output tokens. The action returns a result per model plus cheapestModel and lowestTokenCount summaries.

Text, images, and multiple files

The Files property is a repeatable list:

1. Under Files, select Add Item.
2. Map a file from the trigger or previous step into that row's File field.
3. Add another item for every additional file.
4. Map any prompt or instruction into Text; it is combined with all readable files.

Supported text formats include TXT, Markdown, JSON, CSV, common source-code formats, HTML/XML, YAML, SQL, shell scripts, and logs. Supported images are PNG, JPEG, GIF, and WebP. Each file may be up to 10 MB.

Text files are decoded as UTF-8 and joined with blank lines. Every image is measured separately and added to the input total. Image Detail controls OpenAI's low/high image formula; other families use their published rules. Convert PDF and DOCX files to text in an earlier piece and map the result through Text.

Practical flow recipes

Stop expensive requests early

Route the other branch to a notification, summarization, or chunking step. For the model's absolute limit, branch on result.context.overContext.

Pick the cheapest candidate model

Compare the returned ID with provider routes. Keep expected output tokens consistent across candidates.

Measure several uploaded documents

The action returns one combined token count and a source.files audit list showing exactly which uploads were measured.

Understand and map the result

{
  "operation": "count_tokens",
  "source": {
    "characters": 1240,
    "files": [{ "name": "prompt.md", "extension": "md", "bytes": 1240, "extraction": "UTF-8 text decoded inside the Activepieces runtime" }]
  },
  "result": {
    "modelId": "gpt-5.6-terra",
    "inputTokens": 286,
    "cost": { "input": 0.000572, "output": 0, "total": 0.000572 },
    "context": { "remaining": 1049714, "overContext": false }
  }
}

• result.inputTokens: combined token count for text, decoded files, and images.
• result.cost.total: estimated total USD cost.
• result.context.remaining: available context tokens after the input.
• result.context.overContext: boolean suited to a Branch step.
• source.characters: combined decoded-text length.
• source.files: filename, extension, byte size, and extraction method.
• cheapestModel.id: available from Compare Models for provider routing.

Test the Token Calculator step once, then use Activepieces' data picker to select these fields downstream. This is more reliable than typing references manually.

Troubleshooting

• No input: map text, add at least one Files row, or do both.
• Only one upload counted: add a separate Files item for every upload; one row accepts one file.
• Unsupported file type: extract or convert it upstream and map the resulting string to Text.
• Invalid image: confirm it is a real PNG, JPEG, GIF, or WebP rather than a renamed document.
• Piece not found: confirm the full scoped package name and that community npm pieces are permitted.
• Old fields: update to 0.1.1 or later and refresh the flow editor.

Runtime boundary

Processing occurs inside the Activepieces runtime. The piece requires no TokenCalculator.dev account and does not transmit workflow content to TokenCalculator.dev. Execution history, file storage, logs, secrets, and network controls follow the deployment's policies.

Activepieces community-piece documentation · n8n guide · All integrations