--- title: "Helious Credits and Usage: What a Call and a Question Cost" description: "What a Helious credit buys: 1 for an API or MCP call, 10 for an Ask Helious question, 5 for a live answer on a free key, plus the plan allowances and packs." source: Helious canonical: "https://helious.io/usage" --- # Credits and usage Every Helious plan comes with credits. Everything your account does spends from the same wallet: an API or MCP data call, a live answer on a plan that runs an hour behind, a typed question to Ask Helious. This page says what a credit buys, how to get one call live when you are not on Pro, how to read your balance, and what to do when you run low. Reading helious.io costs nothing. **In one minute** - **1 credit** is one data call, on any `/v1` address or any MCP data tool. - **10 credits** is one typed Ask Helious question. - On Free, Squawk and Starter the data is an hour behind. **5 credits** gets one call live: add `fresh=1` to the request, or put `"fresh": true` in the MCP tool's arguments. - Pro and Ultimate are live for 1. Free includes 100 a month, Starter 1,500, Pro 3,000, Ultimate has no cap. - Running low? Two ways on: [a pack or a plan](#more). You choose. ## What a credit buys ActionCreditsNotes A data call on any `/v1` address or any MCP data tool1 Charged when the answer carries data. Every plan but Ultimate, which has no cap. The same call answered live on Free, Squawk or Starter (`fresh=1`)5 News, prints, auctions, boards and prices at the live instant. Costs nothing extra on Pro and Ultimate, and nothing on a lane that is live already (a settlement price, a published rate, Starter's news). A typed Ask Helious question that lands an answer10 Handed back when no answer reaches you. On Pro and Ultimate the preset questions are free. A snapshot on the delayed `/v1/stream` lane, on Free or with no key1 Once a minute while the socket is open. A paid plan's stream takes nothing. `/v1/me`, `/v1/access`, the MCP handshake, `get_access_info`, `list_series`0 How you learn what a credit buys and what you have left. Never charged. Every error, every 429, every market wall served without a key, every empty window0 You pay for data, never for being refused. A charge taken before an error is refunded on the way out. ## What each plan includes PlanCreditsHow the data arrives **Sample, no key**50 a monthShared by everyone calling from your network address. No fresh flag: a free key has one.**Free**100 a monthAn hour behind for 1 credit a call. One call live for 5 with fresh=1.**Starter**1,500 a monthAn hour behind for 1 credit a call. One call live for 5 with fresh=1.**Pro**3,000 a monthEverything live for 1 credit a call. The fresh flag costs nothing extra.**Ultimate**No capNo cap. Fair use: the plan's calls a minute, and 100 typed Ask Helious questions a day. Plan credits come back each period: on your billing date on a paid plan, on the 1st of the month on Free. The new period sets the allowance; it does not add to what is left. Squawk is on the free allowance: the plan is the live voice squawk and nothing else live. Prices and the rest of each plan are on [the pricing page](https://helious.io/pricing). **A worked month on Free.** 100 credits is 100 data calls an hour behind. Or 20 calls live. Or 10 typed questions. Or a mix: 60 held calls, 4 live calls at 5 each (20) and 2 typed questions at 10 each (20) add up to 100. ## Not on Pro? How to get one call live On Free, Squawk and Starter every answer is 60 minutes behind, by the plan's design. When one call has to be current, ask for it on the request: - **Over REST**, add `?fresh=1` to the address. - **Over MCP**, put `"fresh": true` in the tool's arguments. - That one call answers live, for **5 credits** instead of 1. The next call without the flag is an hour behind again, for 1. curl -H "Authorization: Bearer hel_..." "https://api.helious.io/v1/rates?fresh=1" {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_rates_and_curve", "arguments": {"fresh": true}}} The answer tells you which view you got. A live answer's citation line reads "This is live data", its `meta.delay_sec` is 0 and its `meta.fresh` is true. A held answer says how far behind it is, and `meta.live_view` says how to get it live. On a lane that is live for you already (a settlement price, a published rate, the news on Starter) the flag buys nothing, costs nothing, and the answer says so. With fewer than 5 credits left the live call is refused with `out_of_credits` and nothing is charged; the same call without the flag still answers for 1. On Pro and Ultimate every answer is live already, so the flag is accepted and costs nothing extra. Without a key there is no flag: the price addresses answer with the steps to a free key, and the key opens every board. ## Reading your balance Every charged answer carries `X-Credits-Charged` and `X-Credits-Remaining`, and the same two numbers in its `meta` block as `credits_charged` and `credits_left`. `GET https://api.helious.io/v1/me` says what your key is, what is left and when the plan credits come back. `GET https://api.helious.io/v1/access` and the `get_access_info` MCP tool add the whole ladder and the exact next step to relay. Neither costs a credit. In the terminal the balance is under Account, then Subscription, and the Ask Helious drawer shows it under the composer. X-Credits-Charged: 1 X-Credits-Remaining: 2,993 "meta": {"tier": "pro", "fresh": true, "credits_charged": 1, "credits_left": 2993, ...} ## When the wallet is empty The call is refused with HTTP 429 and the code `out_of_credits`. Nothing is charged for a refusal. The body says what to do: `credits_left`, `resets_on` (when the plan credits come back), `retry_after_seconds`, `next_step` (one sentence to relay), `packs` (the code, credits and price of each pack on sale), `topup_url` while a pack is on sale, `upgrade_url` and, on Free, Squawk and Starter, `fresh_costs`, so a refused `fresh=1` call can say why 5 were needed. The MCP server relays the same body as an `isError` tool result, and the delayed stream closes with it when a minute's snapshot cannot be paid for. `/v1/me` and `/v1/access` still answer, so an empty wallet never hides the page that explains it. Ultimate has no credit cap. HTTP/1.1 429 Too Many Requests Retry-After: 86400 {"error": {"code": "out_of_credits", "credits_left": 3, "resets_on": "2026-11-01", "next_step": "A person buys a pack at https://helious.io/pricing#credits or a plan at https://helious.io/pricing; ...", "packs": [{"code": "credits_500", "credits": 500, "price": "$9.99"}, ...], "topup_url": "https://helious.io/pricing#credits", "upgrade_url": "https://helious.io/pricing", "fresh_costs": 5, "message": "..."}} ## Running low? Two ways on When the credits run low there are two ways to keep going, and you choose. Either lands on your account within a minute, and nothing about an API integration changes. ### A pack, now A one-off charge, bought in the terminal under Account, then Subscription, or from the Ask Helious drawer when it offers one: **500 credits for $9.99** or **1,500 credits for $24.99**. Every plan can buy one, Free included. - Bought credits never expire. - They are spent after your plan's, so buying early is never wasted. - Pick a pack when you need a few hundred more calls this month and the hour's delay is fine. ### A plan, every month More credits every month, and fresher data. Starter has 1,500 credits a month with the news live. Pro has 3,000 with everything live and the terminal. Ultimate has no cap. - Pick a plan when you run out most months. - Pick a plan when you need the data live, or the news live, or the terminal. - Many people do both: a plan for the month, a pack for a heavy week. Credits buy usage; your plan sets how fresh the data is, and a live answer on a free key is 5 credits. [See the plans →](https://helious.io/pricing) [Buy a pack in the terminal →](https://helious.io/) ## Ask Helious A typed question costs 10 credits from the same wallet, charged once however many tools the answer reaches for, and handed back when no answer lands. On Pro and Ultimate the preset questions on the opening screen are free. On Free, Squawk and Starter the assistant answers an hour behind; on Pro and Ultimate it is live. Questions about Helious itself, its plans and how to buy never spend credits. Ultimate spends nothing and has a fair-use limit of 100 typed questions a day. More in the [help centre](https://helious.io/help/ask-helious). ## What changed on 19 October 2026 Before this, the free API had a daily call budget and Ask Helious had credits of its own, and the two could not see each other. Now there is one wallet. Free went from a question a day to 100 credits a month and every price board an hour behind. Pro went from a monthly Ask allowance to 3,000 credits a month for everything. A question went from 1 credit to 10, so every balance already on an account was multiplied by ten on the same day: a person holding seven questions still holds seven questions. ## FAQ ### What is a Helious credit? The unit every plan is measured in. One wallet pays for everything your account does. An API or MCP data call is 1 credit. A typed Ask Helious question is 10. On Free, Squawk and Starter one call answered live is 5. Free includes 100 a month, Starter 1,500, Pro 3,000, Ultimate has no cap. Reading the pages on helious.io costs nothing. ### I am not on Pro. How do I get a live answer? Ask for it on the request. Over REST, add ?fresh=1 to the address. Over MCP, put "fresh": true in the tool's arguments. That one call answers live for 5 credits instead of 1, and the answer says so. The next call without the flag is an hour behind again, for 1. Pro and Ultimate are live already, so the flag costs nothing extra there. ### How do I see how many credits I have left? Every charged answer carries two headers, X-Credits-Charged and X-Credits-Remaining, and the same two numbers in its meta block as credits_charged and credits_left. GET /v1/me and GET /v1/access (or the get_access_info MCP tool) say what is left and when the plan credits come back, and they never cost a credit. In the terminal the balance is under Account, then Subscription. ### What happens when I run out? The call is refused with HTTP 429 and the code out_of_credits, and nothing is charged. The body says how many credits are left, when the plan credits come back, and the two ways on: the packs with their prices and the link to the plans. /v1/me and /v1/access still answer. A pack of 500 credits is $9.99; bought credits never expire. Ultimate has no credit cap. ### Should I buy a pack or move to a plan? A pack when you need a few hundred more calls this month and the hour's delay is fine: 500 credits for $9.99 or 1,500 for $24.99, a one-off charge that never expires. A plan when you run out most months, or when you need the data live: Starter has 1,500 credits a month with live news, Pro 3,000 with everything live, Ultimate no cap. Either lands within a minute. Many people do both: a plan for the month, a pack for a heavy week. ### Do credits roll over? Plan credits do not. A new period sets the allowance rather than adding to what is left, on your billing date for a paid plan and on the 1st of the month on Free. Bought credits are different: they never expire and are only spent once the plan credits are gone. The API reference is at [helious.io/developers](https://helious.io/developers/), the assistant setup at [helious.io/ai](https://helious.io/ai/), the help centre's [credits and packs](https://helious.io/help/credits) article covers the terminal, and every plan with its price is at [helious.io/pricing](https://helious.io/pricing).