LangChain

Use tokenusage.dev tools with LangChain

Four free, read-only, keyless tools for Codex reset announcements, the UTC reset calendar, and Nerf Watch scores and history.

Install

Use Python 3.10 or newer. No tokenusage.dev API key, account or subscription is required.

pip install langchain-tokenusage-dev

The package depends on langchain-core>=1.0,<2 and uses Python's standard library for HTTP.

Call all four tools without a model

TokenUsageToolkit returns all four LangChain tools. This example calls them directly and prints each dataset's credit link:

import json

from langchain_tokenusage_dev import TokenUsageToolkit

tools = {tool.name: tool for tool in TokenUsageToolkit().get_tools()}


def show(result):
    if isinstance(result, str):
        raise RuntimeError(result)
    print(json.dumps(result, indent=2))
    print(f"[Data: tokenusage.dev]({result['source']})")
    if "qualifier" in result:
        print(result["qualifier"])
    return result


show(tools["get_codex_reset_announcements"].invoke({"limit": 3}))
show(tools["get_codex_reset_calendar"].invoke({"month": "2026-10"}))
scores = show(tools["get_nerfwatch_scores"].invoke({}))

if scores["models"]:
    show(
        tools["get_nerfwatch_history"].invoke(
            {"model": scores["models"][0]["model"]}
        )
    )

You can also pass these BaseTool instances to your configured LangChain agent. The agent's model package and provider credentials are separate from these keyless tools.

Use an individual tool

from langchain_tokenusage_dev import GetCodexResetAnnouncementsTool

tool = GetCodexResetAnnouncementsTool(timeout=10.0)
result = tool.invoke({"limit": 3})

Available tools

  • get_codex_reset_announcements: recorded @thsottiaux reset announcements, newest first, with post links, times and resetType. Optional integer limit is 1 to 50, default 10.
  • get_codex_reset_calendar: the same at-most-50 announcements grouped by UTC date, newest dates first. Optional month in YYYY-MM filters this window without fetching older announcements.
  • get_nerfwatch_scores: latest scores, previous runs, changes and baselines for at most 100 models, ordered by provider, name and model id. No arguments.
  • get_nerfwatch_history: retained history for one required model id from the scores tool, oldest first, including each point's suite version.

Model ids contain 1–64 lowercase letters, digits, dots, underscores or hyphens, starting with a letter or digit. The three tools that take arguments reject extra keys and explicit null values; like any LangChain tool without arguments, get_nerfwatch_scores ignores input.

Results, caching and errors

Successful calls return JSON-serialisable dictionaries with source. Both Nerf Watch results also include qualifier. The remaining fields and values follow the corresponding MCP tool projections.

The tools read the canonical public JSON endpoints:

GET https://tokenusage.dev/api/resets
GET https://tokenusage.dev/api/nerfwatch

All instances share an in-process cache per endpoint: 15 seconds for resets and 300 seconds for Nerf Watch, measured from request start. Failed reads use the same cache interval. Concurrent calls share the read. There is no background polling or automatic retry.

Please poll no faster than every 15 seconds for resets and every 5 minutes for Nerf Watch. Use canonical URLs without cache-busting query strings. Requests identify the package and its repository in the User-Agent.

The default HTTP timeout is 10 seconds. HTTP failures, timeouts, invalid responses, invalid arguments and unknown model ids become tool error strings through invoke and ainvoke.

Understand the data

Only announcements this monitor recorded from @thsottiaux are shown, at most the 50 newest; this is not a complete history. A date without an entry does not mean no reset was announced. A banked reset grant saves a reset for eligible users to apply later and does not itself refill limits. An announcement is not proof that any account's limit was reset; open its source post for the wording and eligibility.

Nerf Watch preserves missing days and suite versions. Scores and changes are rounded to two decimals by the API; comparisons are within one suite version. Read the returned baseline and retention settings. The package does not recalculate scores, baselines or trends.

Reuse and credit

When showing reset data to other people, show Data: tokenusage.dev on the same screen or in the same message.

When showing Nerf Watch scores, changes, history or metadata to other people, show Data: tokenusage.dev on the same screen or in the same message. Personal use needs no visible credit.

API and other relays must retain each dataset's source URL and pass on its credit condition. Anyone displaying the data must show its applicable credit.

A lower score is a lower score on this suite, not proof that a provider changed a model: runs are noisy, and a provider's defaults, the endpoint or the runner itself can change.

Retain that qualification when displaying scores or changes. The MIT licence covers the package's code; service data remains subject to the credit conditions above.

tokenusage.dev is unofficial and not affiliated with OpenAI or Anthropic. See Developers for the API reference, Nerf Watch method for measurement details, and Terms for reuse conditions.

Package source and issues · PyPI package