← Back to blog

Count LLM Tokens Before You Send Them: A Free Token Count API for Agents

September 30, 2026 · Eric · 8 min read

Every prompt you send to a language model is billed and windowed in tokens, not characters. That mismatch is where agent runs get expensive: a document that looks like 40 KB of text can be 11,000 tokens of context, and a retrieval step that pastes three of those into one call quietly burns a budget you never approved. Counting first is cheaper than discovering the problem at HTTP 400 or on the invoice.

This post is about the token counter on Agent Media Tools: POST /api/token-count. It is a free endpoint, it needs no API key for basic use, and it returns per-model token estimates plus a cost estimate in the same response — which makes it a practical pre-flight check for agent code, not just a browser toy.

Why count before the call

The endpoint

One POST, a JSON body, and a JSON response:

FieldRequiredNotes
textYesThe string to count. Maximum 2,000,000 characters per request.
modelsNoArray of model names. Defaults to gpt-4o, claude-3-5-sonnet, llama-3, and mistral.

curl

curl -X POST https://agentmediatools.com/api/token-count \
  -H "Content-Type: application/json" \
  -d '{"text":"Count these tokens before you send them to a model."}'

A successful call returns the following shape — field names, nesting, and the trailing note are exactly what the endpoint produces, and the numbers are the counter's output for that 51-character input:

{
  "success": true,
  "char_count": 51,
  "word_count": 10,
  "line_count": 1,
  "tokens": {
    "gpt-4o": 10,
    "claude-3-5-sonnet": 10,
    "llama-3": 11,
    "mistral": 10
  },
  "cost_estimates_usd": {
    "gpt-4o":           { "per_1k_calls": 0.025,  "per_call": 0.000025 },
    "claude-3-5-sonnet":{ "per_1k_calls": 0.03,   "per_call": 0.00003 },
    "llama-3":          { "per_1k_calls": 0,      "per_call": 0 },
    "mistral":          { "per_1k_calls": 0.0025, "per_call": 0.000003 }
  },
  "note": "Token counts are estimates using BPE approximation (±5-10% vs actual tokenizer)"
}

Three things are worth noticing. First, the model estimates differ for identical text — llama-3 is slightly more granular than gpt-4o in this estimator. Second, cost_estimates_usd gives you both a per-call figure and a per-1,000-calls figure, so you can size a batch job without a spreadsheet. Third, char_count, word_count, and line_count come back free with the same call, which is handy when a workflow needs both a size gate and a readability signal.

Python: gate a document before you send it

Here is the same call in Python using the requests library. This is a plain REST endpoint, so there is no SDK to install and no client to keep in sync:

import requests

def token_report(text, models=None, timeout=15):
    payload = {"text": text}
    if models:
        payload["models"] = models
    r = requests.post(
        "https://agentmediatools.com/api/token-count",
        json=payload,
        timeout=timeout,
    )
    r.raise_for_status()
    return r.json()

report = token_report(open("policy.md", encoding="utf-8").read())
print(report["tokens"])                       # per-model token estimates
print(report["cost_estimates_usd"]["gpt-4o"])  # {'per_1k_calls': ..., 'per_call': ...}

CONTEXT_WINDOW = 128_000
RESERVED_FOR_OUTPUT = 4_000
if report["tokens"]["gpt-4o"] > CONTEXT_WINDOW - RESERVED_FOR_OUTPUT:
    print("Too big for one call — chunk it first.")

The shape of that guard is the whole point: read the file, ask how big it is in tokens, and decide before you spend a model call finding out.

Choosing which models to count

Pass models when you only care about one or two targets, or when you want a model the defaults do not include:

curl -X POST https://agentmediatools.com/api/token-count \
  -H "Content-Type: application/json" \
  -d '{"text":"Route this prompt to a cheaper model.","models":["gemini-1.5","mistral"]}'

The estimator recognises gpt-4o, gpt-4, gpt-3.5-turbo, claude-3, claude-3-5-sonnet, llama-3, mistral, and gemini-1.5, applying a small per-family adjustment on top of the base count. An unrecognised name still returns a count — it simply falls back to the neutral factor, which is useful when you are comparing an internal model alias against a frontier model.

One asymmetry to know about: the cost table is narrower than the token table. Cost estimates are only produced for gpt-4o, claude-3-5-sonnet, llama-3, and mistral. Ask for gemini-1.5 and you get a token count with no cost entry, and llama-3 is priced at zero because it is assumed self-hosted. Treat those figures as the built-in reference prices of the counter, and confirm current rates on your provider's pricing page before you commit to a budget number in a contract or a CI threshold.

How accurate is the estimate?

The response says it plainly: the counts come from a byte-pair-encoding (BPE) approximation and land within roughly ±5–10% of a real tokenizer. That is honest and it matters. The estimator works in buckets — short words count as one token, longer words scale with length, punctuation and digits add fractions, newlines add a little, and non-ASCII characters such as CJK text or emoji cost more because they take multiple bytes. Real tokenizers do not segment that mechanically, so the two will diverge on unusual input:

A good pattern is to use the API as a cheap, provider-neutral first pass and only reach for an exact local tokenizer when a number is going to be audited. For most agent loops, the estimate is the difference between a 4,000-token call and a rejected one.

Budgeting a context window

A workable mental model for a single call:

budget = context_window
       - system_prompt_tokens
       - tool_schema_tokens
       - retrieved_context_tokens
       - expected_output_tokens
       - safety_margin

Each of those terms is measurable with the same endpoint: count the system prompt once and cache it, count your tool schemas once per agent version, count the retrieval payload per request, and reserve the output budget separately. Then chunk the document to fit what is left:

import requests

API = "https://agentmediatools.com/api/token-count"

def tokens(text, model="gpt-4o"):
    r = requests.post(API, json={"text": text, "models": [model]}, timeout=15)
    r.raise_for_status()
    return r.json()["tokens"][model]

def chunk_to_budget(text, budget, model="gpt-4o"):
    """Split on blank lines, then verify each chunk against the real budget."""
    chunks, current = [], []
    for para in text.split("\n\n"):
        trial = "\n\n".join(current + [para])
        if current and tokens(trial, model) > budget:
            chunks.append("\n\n".join(current))
            current = [para]
        else:
            current.append(para)
    if current:
        chunks.append("\n\n".join(current))
    return chunks

for i, chunk in enumerate(chunk_to_budget(open("handbook.md", encoding="utf-8").read(), 3000)):
    print(i, tokens(chunk))  # every chunk verified inside the budget

Splitting on paragraph boundaries and then measuring is deliberately boring: it keeps the number of counting calls proportional to the number of chunks, and it never trusts a character heuristic for the final decision.

Limits, quotas, and error handling

The counter is a free tool on the platform's shared free-tool pool, which means calls count toward the same daily allowance as other free utilities rather than a per-tool bucket of their own. Anonymous requests get 10 calls per day per IP; a free account raises that to 25 per day; paid plans raise it further, and agent keys carry their own daily limit when you authenticate with Authorization: Bearer mt_….

One detail that makes the counter pleasant to call speculatively: the daily gate checks your allowance first and only consumes it when the request actually succeeds, so a malformed payload or a failed call does not cost you quota. Failures come back as ordinary JSON:

StatusCode / bodyWhat it means
400{"error":"text required"}No text field in the body, or it was empty.
400{"error":"Max 2MB text"}text exceeded 2,000,000 characters. Chunk it.
429ANON_DAILY_LIMITAnonymous allowance used up for this IP; the body points at free registration.
429FREE_USER_DAILY_LIMIT / PAID_DAILY_LIMITSigned-in user hit the daily cap for their plan.
429AGENT_FREE_DAILY_LIMIT / AGENT_PAID_DAILY_LIMITAgent key hit its own daily limit; the body includes limit and used.

Because the 429 body carries limit, used, and a suggested action, an agent can back off cleanly instead of retrying blindly: treat 429 as a scheduling signal, queue the work, and retry after the daily reset rather than burning the rest of your run on refusals.

Patterns worth automating

None of this requires a local tokenizer, a heavyweight SDK, or a provider account. It is one JSON POST, and it works the same whether the caller is a Python script, a scheduler, or an agent deciding what to send next.

Try it in the Toolbox

Paste text into the Token Counter to see per-model estimates and cost instantly, or call the same endpoint from your agent.

Open the Token Counter