{"version":"2.1.267","anchor":"new-scriptable-session-usage-api-sessionusage","canonical_anchor":"new-scriptable-session-usage-api-sessionusage","heading":"New scriptable session-usage API ($.session.usage)","tier":"use","area":"SDK","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.267\/e\/new-scriptable-session-usage-api-sessionusage","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.267","markdown":"### New scriptable session-usage API ($.session.usage)\n\nA new scripting API, $.session.usage, exposes context, rate-limit, and cost data to plugins and scripts\n\n**What**\n\nA new function called `$.session.usage` is now available for scripting and plugin code. It returns details about the current session, including:\n\n- context-window usage (how many tokens are used, the size of the window, and the percentage full)\n\n- rate-limit windows (`five_hour`, `seven_day`, and `spend_limit`), each with a percent used and when it resets\n\n- the current session's cost in US dollars\n\n**Why**\n\nThis lets plugins and other scripts built on top of Claude Code read the same usage and cost figures Claude Code itself tracks, instead of guessing or parsing them from elsewhere. That makes it possible to build custom status lines, dashboards, or automations that react to how close a session is to its context or rate limits.\n\n- Area: SDK\n- Tier: Use it now\n- Useful: 5\/5\n- Signal: 3\/5"}