> ## 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. # ETF detail > Full detail view for a single ETF — descriptive metadata, latest price, top holdings, valuation ratios, sector weights, net-flow history and cumulative-return performance by period. Use the exchange ticker (e.g. a TSE code like `1306`) as the `{code}` path param. ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/etf/{code}/detail 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 and real-estate 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.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: >- Real-estate statistics, land prices, administrative geography (provinces / wards) and choropleth GeoJSON, by country. paths: /openapi/v1/etf/{code}/detail: get: tags: - ETF summary: ETF detail description: > Full detail view for a single ETF — descriptive metadata, latest price, top holdings, valuation ratios, sector weights, net-flow history and cumulative-return performance by period. Use the exchange ticker (e.g. a TSE code like `1306`) as the `{code}` path param. operationId: etfDetail parameters: - name: code in: path required: true description: Exchange ticker for the ETF (e.g. a TSE code like `1306`). schema: type: string example: '1306' responses: '200': description: Full detail view for the ETF. content: application/json: schema: $ref: '#/components/schemas/EtfDetailResponse' example: success: true statusCode: 200 data: etfCode: '1306' etfName: NEXT FUNDS TOPIX Exchange Traded Fund managementCompany: Nomura Asset Management MER: 0.0505 etfType: Japanese Equity(Market) indexName: TOPIX Total Return Index listingDate: '2001-07-13' currentPrice: 425.5 change: 2.4 changePct: 0.57 lastUpdateDate: '2026-06-17' totalAssetValue: 32511066650608.5 AssetAllocation: - name: TOYOTA MOTOR CORP value: 1074907641000 - name: MITSUBISHI UFJ FIN value: 1063805290650 equityHoldings: PE: '0.0600' PB: '0.6400' PS: '0.8400' PC: '0.0900' sectorWeight: - sector: null weight: 0.2803 month: 4 year: 2026 distributionYield: 0.0176 netflow: data: - date: '2025-10-17' aum: 26913496133220 netflow: -26107300968 netflowAumPct: -0.097 periodAvailability: 1M: true 3M: true 6M: true performance: periodAvailability: 1M: true 3M: true 6M: true 1Y: true 3Y: true periods: 1M: - date: 15-05-2026 nav: 409.9 cumulativeReturn: 0 - date: 18-05-2026 nav: 405.9 cumulativeReturn: -0.98 meta: timestamp: '2026-06-19T08:50:39.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: EtfDetailResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: $ref: '#/components/schemas/EtfDetail' 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' EtfDetail: type: object description: | Full detail view for a single ETF — descriptive metadata, latest price, top holdings, valuation ratios, sector weights, net-flow history and cumulative-return performance. required: - etfCode - etfName - managementCompany - etfType properties: etfCode: type: string description: Exchange ticker for the ETF. example: '1306' etfName: type: string description: Fund name. example: NEXT FUNDS TOPIX Exchange Traded Fund managementCompany: type: string description: Asset manager operating the fund. example: Nomura Asset Management MER: type: number description: Management expense ratio, as a fraction. example: 0.0505 etfType: type: string description: Asset-class / strategy classification. example: Japanese Equity(Market) indexName: type: string description: Benchmark index the fund tracks. example: TOPIX Total Return Index listingDate: type: string format: date description: Date the ETF was first listed. example: '2001-07-13' currentPrice: type: number description: Latest market price. example: 425.5 change: type: number description: Absolute price change versus the previous close. example: 2.4 changePct: type: number description: Percentage price change versus the previous close. example: 0.57 lastUpdateDate: type: string format: date description: Date the snapshot was last updated. example: '2026-06-17' totalAssetValue: type: number description: Total net asset value, in fund currency. example: 32511066650608.5 AssetAllocation: type: array description: Top holdings by market value. items: $ref: '#/components/schemas/EtfDetailHolding' equityHoldings: $ref: '#/components/schemas/EtfEquityHoldings' sectorWeight: type: array description: Sector weights for the latest reporting month. items: $ref: '#/components/schemas/EtfSectorWeight' distributionYield: type: number description: Trailing distribution yield, as a fraction. example: 0.0176 netflow: $ref: '#/components/schemas/EtfNetflowHistory' performance: $ref: '#/components/schemas/EtfPerformance' 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 EtfDetailHolding: type: object description: One top holding contributing to an ETF's net asset value. required: - name - value properties: name: type: string description: Name of the holding. example: TOYOTA MOTOR CORP value: type: number description: Market value of the position, in fund currency. example: 1074907641000 EtfEquityHoldings: type: object description: Aggregate valuation ratios for the ETF's equity holdings. properties: PE: type: string description: Portfolio price-to-earnings ratio. example: '0.0600' PB: type: string description: Portfolio price-to-book ratio. example: '0.6400' PS: type: string description: Portfolio price-to-sales ratio. example: '0.8400' PC: type: string description: Portfolio price-to-cash-flow ratio. example: '0.0900' EtfSectorWeight: type: object description: One sector weight in an ETF's portfolio for a given month. required: - weight properties: sector: type: - string - 'null' description: Sector name; `null` when uncategorised. example: Financials weight: type: number description: Sector weight as a fraction of the portfolio. example: 0.2803 month: type: integer description: Reporting month (1–12). example: 4 year: type: integer description: Reporting year. example: 2026 EtfNetflowHistory: type: object description: An ETF's net-flow history with the set of available period windows. required: - data - periodAvailability properties: data: type: array description: Net-flow observations, ordered oldest to newest. items: $ref: '#/components/schemas/EtfNetflowPoint' periodAvailability: type: object description: Which period windows have data, keyed by period. additionalProperties: type: boolean example: 1M: true 3M: true 6M: true EtfPerformance: type: object description: An ETF's cumulative-return performance, grouped by period window. required: - periodAvailability - periods properties: periodAvailability: type: object description: Which period windows have data, keyed by period. additionalProperties: type: boolean example: 1M: true 3M: true 6M: true 1Y: true 3Y: true periods: type: object description: Performance series grouped by period window (e.g. `1M`, `1Y`). additionalProperties: type: array items: $ref: '#/components/schemas/EtfPerformancePoint' example: 1M: - date: 15-05-2026 nav: 409.9 cumulativeReturn: 0 - date: 18-05-2026 nav: 405.9 cumulativeReturn: -0.98 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 EtfNetflowPoint: type: object description: One net-flow observation in an ETF's net-flow history. required: - date - netflow properties: date: type: string format: date description: Observation date. example: '2025-10-17' aum: type: number description: Assets under management on the date, in fund currency. example: 26913496133220 netflow: type: number description: Net capital flow on the date, in fund currency. example: -26107300968 netflowAumPct: type: number description: Net flow as a percentage of assets under management. example: -0.097 EtfPerformancePoint: type: object description: One point in an ETF's cumulative-return performance series. required: - date - nav - cumulativeReturn properties: date: type: string description: Observation date (DD-MM-YYYY). example: 15-05-2026 nav: type: number description: Net asset value per share on the date. example: 409.9 cumulativeReturn: type: number description: Cumulative return since the period start, in percent. example: -0.98 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' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 404 error: code: INTERNAL_ERROR message: Commodity 'zzz-nope' not found meta: error: Not Found statusCode: 404 timestamp: '2026-06-19T08:34:08.205Z' 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. ````