> ## Documentation Index > Fetch the complete documentation index at: https://developer.hayinsights.com/llms.txt > Use this file to discover all available pages before exploring further. # Economic calendar events > Scheduled economic events in a date range — rate decisions, CPI and GDP releases, holidays. Defaults to the next 30 days when `from` / `to` are omitted. Filter by `country` (us, jp, vn, …) and `impact` (high, medium, low) to keep a daily briefing to the events that move markets. Filters accept a comma-separated list. The response reports `total`, so page with `offset` when there is more than one page. ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/calendar/events openapi: 3.1.0 info: title: HayInsights Open API version: 0.1.0 description: > Programmatic access to the **HayInsights** financial-data hub — commodities, crypto, ETF, FX, macroeconomic, real-estate, news, economic-calendar and market-index datasets, served from a single API surface under `/openapi/v1/*`. This specification is the **single source of truth** for the public API surface — shared by SDK codegen, the reference docs, and (later) the mock server / contract tests. ## Authentication Every request must carry your API key in the `X-API-Key` header. There is a single authentication tier — no request signing. Create and manage keys in the HayInsights dashboard (Account → API keys). See **Authentication**. ## Plans & quota Access to each data domain and your request quota are governed by the subscription plan attached to your key. Each endpoint consumes a **weighted** amount of your per-minute quota; every response carries `X-RateLimit-*` headers. See **Rate limits** and **Plans & features**. contact: {} servers: - url: https://api-v2.hayinsights.com description: Production security: - HayInsightsApiKey: [] tags: - name: Commodities description: >- Spot prices, top movers, gold–DXY correlation and historical series for energy, metals and agricultural commodities. - name: Crypto description: >- Crypto market overview, dominance, bubble map, on-chain and derivatives metrics. - name: ETF description: >- Exchange-traded fund listings, performance & net-flow rankings, heatmap, holdings, NAV growth and fund composition. - name: FX description: >- Foreign-exchange summary, live table, 90-day correlation matrix and the emerging-market stress monitor. - name: Macro description: >- Macroeconomic indicators — GDP, CPI/PCE, exchange rates, population, central-government debt and policy rates / bond yields. - name: Real Estate description: >- Land prices, transaction-level records, administrative geography (provinces / wards) and choropleth GeoJSON, by country. - name: News description: >- Market news headlines with per-article sentiment, plus an aggregate sentiment reading over a rolling window. - name: Calendar description: >- Economic calendar — rate decisions, CPI and GDP releases, market holidays and asset-level events. - name: Market description: >- Index snapshots and global index closes — levels and daily moves for S&P 500, Nasdaq, Nikkei, VN-Index and others. paths: /openapi/v1/calendar/events: get: tags: - Calendar summary: Economic calendar events description: > Scheduled economic events in a date range — rate decisions, CPI and GDP releases, holidays. Defaults to the next 30 days when `from` / `to` are omitted. Filter by `country` (us, jp, vn, …) and `impact` (high, medium, low) to keep a daily briefing to the events that move markets. Filters accept a comma-separated list. The response reports `total`, so page with `offset` when there is more than one page. operationId: calendarEvents parameters: - name: from in: query required: false description: Start date, `YYYY-MM-DD`. schema: type: string format: date example: '2026-09-01' - name: to in: query required: false description: End date, `YYYY-MM-DD`. schema: type: string format: date example: '2026-09-30' - name: country in: query required: false description: > Filter by country. Comma-separated, e.g. `us,jp,vn`. An unrecognised value yields an empty list rather than every event. schema: type: array items: type: string enum: - global - us - jp - vn - eu - gb - au - ca - nz - cn - ch style: form explode: false - name: category in: query required: false description: | Filter by event type. Comma-separated. | Value | Description | | --- | --- | | `holiday` | Market holidays | | `economic` | Macroeconomic releases | | `asset` | Asset-level events (dividends, rebalances) | schema: type: array items: type: string enum: - holiday - economic - asset style: form explode: false - name: assetClass in: query required: false description: Filter by asset class. Comma-separated. schema: type: array items: type: string enum: - stock - etf - bond - crypto - commodity - fx style: form explode: false - name: impact in: query required: false description: Filter by expected market impact. Comma-separated. schema: type: array items: type: string enum: - high - medium - low style: form explode: false - name: q in: query required: false description: Search the event title, local name, or tag. schema: type: string example: CPI - name: includeGlobal in: query required: false description: Include global events alongside the countries selected. schema: type: boolean default: true - name: tz in: query required: false description: IANA timezone the event times are rendered in. schema: type: string example: Asia/Tokyo - name: preset in: query required: false description: Preset filter bundle. schema: type: string enum: - global - name: limit in: query required: false description: Events to return. schema: type: integer minimum: 1 maximum: 50 default: 20 - name: offset in: query required: false description: Events to skip, for paging. schema: type: integer minimum: 0 default: 0 responses: '200': description: One page of calendar events. content: application/json: schema: $ref: '#/components/schemas/CalendarEventsResponse' example: success: true statusCode: 200 data: total: 150 returned: 2 offset: 0 items: - id: '48213' date: '2026-09-17' time: '14:30:00' timezone: America/New_York timezoneLabel: ET country: us category: economic assetClass: null title: CPI (YoY) titleLocal: null description: Consumer price index, year over year. impact: high actual: null forecast: 3.1 previous: 3.2 unit: percent actualText: null forecastText: 3.1% previousText: 3.2% symbols: [] subgroup: null source: investing.com sourceUrl: https://www.investing.com/economic-calendar/cpi-733 - id: '48377' date: '2026-09-21' time: null timezone: Asia/Tokyo timezoneLabel: JST country: jp category: holiday assetClass: null title: Respect for the Aged Day titleLocal: 敬老の日 description: null impact: low actual: null forecast: null previous: null unit: null actualText: null forecastText: null previousText: null symbols: [] subgroup: null source: jpx sourceUrl: null meta: timestamp: '2026-09-16T08:50:42.507Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: CalendarEventsResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: type: object description: > One page of events. `total` counts every event matching the filters, so a caller told "150 events, 20 returned" can reach the rest with `offset`. required: - total - returned - offset - items properties: total: type: integer example: 150 returned: type: integer example: 20 offset: type: integer example: 0 items: type: array items: $ref: '#/components/schemas/CalendarEvent' EnvelopeBase: type: object description: > Standard success envelope shared by every endpoint. Each operation's response wrapper extends this (via `allOf`) and adds a typed `data` property. required: - success - statusCode properties: success: type: boolean const: true description: Always `true` for a successful response. example: true statusCode: type: integer description: Mirrors the HTTP status code. example: 200 meta: $ref: '#/components/schemas/Meta' CalendarEvent: type: object description: > One scheduled event. `date` and `time` are the local date–time at the publishing market, **not** converted to the caller's timezone — `timezoneLabel` says which market that is. required: - id - date - country - category - title - symbols - source properties: id: type: string example: '48213' date: type: string format: date example: '2026-09-17' time: type: - string - 'null' description: '`null` for an all-day event.' example: '14:30:00' timezone: type: - string - 'null' description: IANA timezone of the publishing market. example: America/New_York timezoneLabel: type: - string - 'null' description: Short label for the timezone `date` / `time` are expressed in. example: ET country: type: string enum: - global - us - jp - vn - eu - gb - au - ca - nz - cn - ch example: us category: type: string enum: - holiday - economic - asset example: economic assetClass: type: - string - 'null' enum: - stock - etf - bond - crypto - commodity - fx - null description: '`null` for holidays and pure macro releases.' example: etf title: type: string example: CPI (YoY) titleLocal: type: - string - 'null' description: Native-language name, where the source publishes one. example: 消費者物価指数 description: type: - string - 'null' impact: type: - string - 'null' enum: - high - medium - low - null example: high actual: type: - number - 'null' description: Published figure; `null` until release time. example: 2.9 forecast: type: - number - 'null' example: 3.1 previous: type: - number - 'null' example: 3.2 unit: type: - string - 'null' description: Unit of `actual` / `forecast` / `previous`. example: percent actualText: type: - string - 'null' description: Source's own string for the figure — render verbatim when present. example: 2.9% forecastText: type: - string - 'null' example: 3.1% previousText: type: - string - 'null' example: 3.2% symbols: type: array description: Ticker tags attached to the event. items: type: string example: - '1302' - '1305' subgroup: type: - string - 'null' example: No Creation only source: type: string description: Data source — every response names where the figures came from. example: investing.com sourceUrl: type: - string - 'null' format: uri ErrorBody: type: object description: Standard error envelope returned for every 4xx / 5xx response. required: - success - statusCode - error properties: success: type: boolean const: false description: Always `false` for an error response. example: false statusCode: type: integer description: Mirrors the HTTP status code. example: 401 error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/Meta' Meta: type: object description: >- Response metadata. Always present; `timestamp` is the server time the response was generated. required: - timestamp properties: timestamp: type: string format: date-time description: Server time when the response was generated (ISO 8601). example: '2026-06-19T08:31:59.478Z' additionalProperties: true ErrorDetail: type: object description: Error detail object carried under `error` in the error envelope. required: - code - message properties: code: type: string description: > Machine-readable error code. Specific for authentication / quota errors (e.g. `API_KEY_REQUIRED`, `API_KEY_INVALID`, `FEATURE_NOT_IN_PLAN`, `RATE_LIMIT_EXCEEDED`). For validation (400) and not-found (404) the code is currently `INTERNAL_ERROR` and the HTTP status carries the semantics. example: API_KEY_INVALID message: description: Human-readable message, or a list of validation messages (400). oneOf: - type: string - type: array items: type: string example: Invalid API key responses: BadRequest: description: >- Invalid or missing parameter — bad enum, range, format, or a missing required query parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 400 error: code: INTERNAL_ERROR message: - >- Invalid type parameter. Must be "gdp", "cpi", "pce", or "import-export" - Type parameter is required meta: error: Bad Request statusCode: 400 timestamp: '2026-06-19T08:34:08.081Z' Unauthorized: description: >- Missing, invalid, disabled or expired API key. Send a valid key in the `X-API-Key` header. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 401 error: code: API_KEY_INVALID message: Invalid API key meta: timestamp: '2026-06-19T08:34:08.023Z' Forbidden: description: >- Your subscription plan does not include this data feature, or your key's scope denies it. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 403 error: code: FEATURE_NOT_IN_PLAN message: Your plan does not include this feature meta: timestamp: '2026-06-19T08:34:08.100Z' RateLimited: description: > Rate limit exceeded — you have consumed your plan's per-minute weight budget. Wait until `X-RateLimit-Reset` (or `Retry-After` seconds) then retry. headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-RateLimit-Weight-Used: $ref: '#/components/headers/XRateLimitWeightUsed' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 429 error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded meta: timestamp: '2026-06-19T08:34:09.000Z' InternalError: description: Unexpected server error. Retry after a short exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 500 error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2026-06-19T08:34:10.000Z' headers: XRateLimitLimit: description: Your plan's request-weight budget per 1-minute window. schema: type: integer example: 1000 XRateLimitRemaining: description: Remaining request weight in the current 1-minute window. schema: type: integer example: 997 XRateLimitReset: description: Unix timestamp (seconds) when the current rate-limit window resets. schema: type: integer format: int64 example: 1781857979 XRateLimitWeightUsed: description: Request weight consumed by this call (see each endpoint's weight). schema: type: integer example: 3 RetryAfter: description: Seconds to wait before retrying. Present on 429 responses. schema: type: integer example: 30 securitySchemes: HayInsightsApiKey: type: apiKey in: header name: X-API-Key description: > Your HayInsights API key (prefixed `apk_`). Create and manage keys in the HayInsights dashboard (Account → API keys). Send it in the `X-API-Key` header on **every** request to `/openapi/v1/*`. Which data domains you may access and your request quota are both governed by the subscription plan attached to the key — see the **Plans & features** and **Rate limits** guides. ````