Helious Series API

openapi: 3.2.0
info:
  title: Helious Public Series API
  version: '2026-11-06'
  summary: Real-time US economic releases, Treasury auction results, rates and market news from the Helious desk.
  description: 'Read-only surface of api.helious.io. Every dataset here is first-party: captured by the Helious desk the moment it prints, with methodology at https://helious.io/methodology. On /v1/feed and the stream the Helious news wire rides beside the desk''s own posts: a wire headline is marked kind: headline and scored like everything else. The /v1 endpoints are the versioned contract for agents, and every tier sees the same endpoints and the same response shapes: only the history window, the delay and the market-data axis change, so an integration built keyless survives every upgrade untouched. The ladder: Sample (no key, no account, $0) gets 1 day of history, news and prints 1 hour behind, no market prices at all (price endpoints answer with the upgrade steps instead of numbers) and 30 calls a minute and 50 credits a month, shared by everyone on your network address. Free (a key on a free helious.io account, $0) gets 7 days of history, news 1 hour behind, every price board 60 minutes behind, and 60 calls a minute and 100 credits a month of your own. ONE CREDIT WALLET pays for everything an account does: a data call on any /v1 endpoint or MCP tool is 1 credit, a typed Ask Helious question in the terminal is 10, and on Free, Squawk and Starter the query fresh=1 (fresh: true as an MCP tool argument) answers that one call live for 5 credits. /v1/me, /v1/access, the MCP handshake, get_access_info, list_series, every error and every refusal are free; a keyless market wall is free too. Every answer carries X-Credits-Charged and X-Credits-Remaining headers and the same two numbers in meta (credits_charged, credits_left), and an empty wallet is a 429 with code out_of_credits carrying credits_left, resets_on, next_step (one sentence to relay), the packs that top it up (500 for $9.99, 1,500 for $24.99, never expiring) and upgrade_url: two ways on, a pack or a plan, and the person who owns the key chooses. Not on Pro and need one call live? Add fresh=1 to that request (fresh: true in an MCP tool''s arguments) and it answers live for 5 credits. Each delayed stream snapshot takes one credit on Free and with no key; a paid plan''s stream takes none. Starter ($14.99/mo or $135/yr) gets 12 months of history, live news and prints, every price board 60 minutes behind (live for 5 credits a call with fresh=1), 1,500 credits a month, at 90 calls a minute. Pro ($39.99/mo or $360/yr) gets 24 months of history, 3,000 credits a month and everything live for 1 credit (yields, treasuries, commodities, equities, FX, volatility, correlations) at 120 calls a minute, the streaming WebSocket included. Ultimate ($99/mo or $891/yr) gets 10 years of history, everything live, no credit cap, commercial use and redistribution, 300 calls a minute and the live stream on 5 connections a key. The stream at wss://api.helious.io/v1/stream is open on every tier, key or no key: below Pro it runs the delayed lane (one snapshot a minute, prices and the ranked NASDAQ-100 board 60 minutes behind, news on the plan''s own delay), and Pro and Ultimate run the live lane (every price tick, print and NASDAQ-100 update pushed the moment it happens, on up to 2 connections a key on Pro and 5 on Ultimate), in identical message shapes, so a stream integration survives the upgrade untouched. Authenticate with the same hel_ key sent as the ''Authorization: Bearer hel_...'' header, never a query parameter; the socket sends a hello whose mode field names your lane, feed items in the /v1/feed shape, price ticks, the ranked NASDAQ-100 board, daily official closes and the Helious momentum score, and answers ''ping'' with pong. Keys are sent as ''Authorization: Bearer hel_...''; GET /v1/access returns the ladder and the exact upgrade steps in plain words. There is also an MCP server at https://api.helious.io/mcp: point any MCP client at that URL and the same data arrives as tools.'
  x-stream: 'wss://api.helious.io/v1/stream is the live WebSocket, which OpenAPI cannot describe as a path. One socket on every plan: live on Pro (2 connections a key) and Ultimate (5), delayed below Pro (one snapshot a minute). Messages: hello (mode names the lane), feed (items in the /v1/feed shape; a release print is kind post, category release, with the actual, forecast, previous and sigma in its text), prices, ndx, market_data, score (the Helious momentum score when it moves, in the /v1/score shape), and pong to a ping. The hel_ key goes in the Authorization: Bearer header, never a query parameter; no key opens the delayed lane. Documented at https://helious.io/developers/#stream and https://helious.io/developers/economic-calendar-api/#stream.'
  contact:
    name: Helious support
    email: support@helious.news
    url: https://helious.io/contact
  termsOfService: https://helious.news/terms
servers:
- url: https://api.helious.io
tags:
- name: Series
paths:
  /v1/inflation:
    get:
      summary: Every US inflation measure with all four windows worked out
      description: 'Headline and core CPI and PCE, supercore, the trimmed means, the median, the sticky and flexible splits, the CPI components, and what markets expect next. Each measure returns its year-over-year reading plus 1, 3 and 6-month annualised, so no caller has to annualise anything itself. Also reports which parts of the basket are driving the headline rate over the last year. The latest reading answers on every tier, including keyless, because it is a single published figure. For the first 60 minutes after a print that feeds this board, Sample and Free get the board without it, and `held_until` says when it joins. The monthly HISTORY behind it follows your plan''s window (7 days on a free key, 12 months Starter, 24 months Pro, 10 years Ultimate); a call that hits the window still returns the newest month and adds a `plan_limit` block naming the month it reached back to (on Ultimate, the deepest window, a `record_start` block instead: no plan reads further back).'
      tags:
      - Series
      parameters:
      - name: measures
        in: query
        required: false
        description: Comma-separated measure keys, such as core_cpi,core_pce. Omit for all.
        schema:
          type: string
      - name: history
        in: query
        required: false
        description: Add the monthly series for each measure returned, back as far as your plan's history window allows.
        schema:
          type: boolean
          default: false
      - name: window
        in: query
        required: false
        description: Months of history to include when history is true.
        schema:
          type: integer
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      security:
      - {}
      - helious_key: []
      operationId: getV1Inflation
      x-operation-id-source: derived
  /v1/jobs:
    get:
      summary: Every US employment measure with all four windows worked out
      description: 'Total nonfarm payrolls split into private and government, the ten private supersectors, federal, state and local government, ADP''s own private count by sector, initial and continuing jobless claims, and JOLTS openings, hires, quits and layoffs including openings by sector. Each measure returns its monthly change plus 3, 6 and 12-month windows, in THOUSANDS of jobs, so no caller has to difference anything itself. Also reports which sectors drove the headline change, and those parts sum to it exactly because they are counts of people rather than weighted index numbers. Percentages such as the unemployment, participation and quits rates ride in a separate `standing` block, because a percentage and a count cannot share an axis. The latest reading answers on every tier, including keyless, because it is a single published figure. For the first 60 minutes after a print that feeds this board, Sample and Free get the board without it, and `held_until` says when it joins. The monthly HISTORY behind it follows your plan''s window (7 days on a free key, 12 months Starter, 24 months Pro, 10 years Ultimate); a call that hits the window still returns the newest month and adds a `plan_limit` block naming the month it reached back to (on Ultimate, the deepest window, a `record_start` block instead: no plan reads further back).'
      tags:
      - Series
      parameters:
      - name: measures
        in: query
        required: false
        description: Comma-separated measure keys, such as payrolls,edhealth,openings. Omit for all.
        schema:
          type: string
      - name: history
        in: query
        required: false
        description: Add the monthly series for each measure returned, back as far as your plan's history window allows.
        schema:
          type: boolean
          default: false
      - name: window
        in: query
        required: false
        description: Months of history to include when history is true.
        schema:
          type: integer
      - $ref: '#/components/parameters/fresh'
      responses:
        '200':
          description: summary + source + data + meta envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '429':
          description: 'Over the per-minute limit (code rate_limited, Retry-After the rest of the minute) or the wallet cannot pay (code out_of_credits: credits_left, resets_on, retry_after_seconds, packs, topup_url, upgrade_url, and fresh_costs on a held plan). Nothing is charged for a refusal.'
      security:
      - {}
      - helious_key: []
      operationId: getV1Jobs
      x-operation-id-source: derived
components:
  parameters:
    fresh:
      name: fresh
      in: query
      required: false
      schema:
        type: boolean
      description: 'Not on Pro or Ultimate? Add fresh=1 to this request and this one call answers live (news, prints, auctions, boards and prices at the live instant) for 5 credits. Left out, Free, Squawk and Starter get the answer 60 minutes behind for 1 credit. 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. Accepted and free on Pro and Ultimate, where the view is already live. Ignored without a key: a free account key has the flag. Over MCP the same flag is fresh: true in the tool''s arguments.'
  schemas:
    Envelope:
      type: object
      description: Every /v1 response. `summary` states the answer as one plain-English sentence and `source` says who to credit for it, both before the raw `data`, so the finished claim is the first thing a reader meets.
      properties:
        summary:
          type: string
          description: The answer as a sentence, with the numbers in it. Identical to the sentence the matching MCP tool returns.
        source:
          type: object
          description: Who to credit and where a reader can check the number.
          properties:
            name:
              type: string
              example: Helious
            url:
              type: string
              format: uri
              description: The Helious page backing this answer.
            cite_as:
              type: string
              example: Helious, https://helious.io/auctions
            attribution:
              type: string
            live:
              type: string
              description: How current these numbers are on YOUR plan, and how to ask for them again. Says the data is live only on a tier that serves it live.
        data:
          type: object
          description: The dataset itself.
        meta:
          type: object
          description: When it was true, and what your plan allows.
        plan_limit:
          type: object
          description: Present only when your plan moved the window AND Helious holds rows older than it. Says this is a plan limit rather than missing data, where the record begins (record_begins, on the lanes that say it), the plans that reach further, and the exact step to relay to the person you work for.
        record_start:
          type: object
          description: 'Present instead of plan_limit when you asked for more history than any plan reads here: record_begins is the first day any plan reads (null when there is none yet), your plan''s window already reaches it, older_rows_on_any_plan is false, and meta.clamped is false. No plan reaches further back, so there is nothing to upgrade for.'
  securitySchemes:
    helious_key:
      type: http
      scheme: bearer
      description: 'Your Helious API key, like hel_xxx, made on your helious.io account page (Account, then API keys). Every /v1 endpoint also works with no key at the sample tier: 1 day of history, news 1 hour behind, no market prices. A free account key gets 7 days and a rate budget of your own. Starter ($14.99/mo) takes the news live, reaches 12 months back and adds the Treasury curve 60 minutes behind; Pro ($39.99/mo) makes every price live with 24 months of history, the /v1/stream WebSocket included; Ultimate ($99/mo) reaches 10 years, allows commercial use and holds the live stream on 5 connections a key (Pro holds 2).'
    helious_oauth:
      type: oauth2
      description: Sign the person in instead of asking them for a key. Dynamic client registration is open, so your client can enrol itself; the one human step is the consent screen. Access tokens last an hour; ask for offline_access to get a rotating refresh token. Full details at https://helious.io/auth.md.
      flows:
        authorizationCode:
          authorizationUrl: https://helious.io/oauth/authorize
          tokenUrl: https://api.helious.io/oauth/token
          refreshUrl: https://api.helious.io/oauth/token
          scopes:
            market:read: Read Helious market data at that plan level.
            account:read: See which plan the account is on.
            openid: Confirm the account identity to your app.
            offline_access: Get a refresh token so you stay connected.