> ## Documentation Index > Fetch the complete documentation index at: https://docs.beliefsystems.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get volatility history > Belief Volatility history, newest first, clamped to the trailing 90-day window. Each point carries the headline value, every published tenor, the uncertainty band, and the gate names that flagged. The per-leg panel is omitted here; `GET /v1/volatility/{ticker}/latest` carries it for the current tick. `meta` reports `effectiveStart`, `clamped`, and `historyMaxDays`. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/volatility/{ticker}/history openapi: 3.1.0 info: contact: name: Belief Systems url: https://beliefsystems.xyz/data description: >- Rules-based benchmark data for prediction markets: Belief index levels and Belief Volatility series, read over HTTPS with an API key. The API is read-only. Every endpoint is a `GET`, every successful response is `{ data, meta }`, and every failure is a single `error` object with a stable `code`. Keys are free and take about a minute to mint at https://beliefsystems.xyz/data. Attribution is required on anything you publish from this data: "Source: Belief Systems (beliefsystems.xyz)". Production, redistribution, and commercial use require a license (https://beliefsystems.xyz/license). license: name: Belief Systems Data License url: https://beliefsystems.xyz/license termsOfService: https://beliefsystems.xyz/terms title: Belief Systems Data API version: '1.0' servers: - description: Production. There is no separate test host; the API is read-only. url: https://api.beliefsystems.xyz security: - bearerAuth: [] - apiKeyAuth: [] tags: - description: >- Belief indices are rules-based benchmarks of how prediction markets price a defined set of events. Levels are exact decimal strings based at 100 on the index's inception date. name: Indices - description: >- Belief Volatility measures how much prediction-market probabilities are expected to move over a stated horizon, in probability points. Always name the tenor when quoting a value. name: Belief Volatility - description: >- The service index, which reports your key's live quota, and pointers to the free point-in-time snapshot bundles. name: Service paths: /v1/volatility/{ticker}/history: get: tags: - Belief Volatility summary: Get volatility history description: >- Belief Volatility history, newest first, clamped to the trailing 90-day window. Each point carries the headline value, every published tenor, the uncertainty band, and the gate names that flagged. The per-leg panel is omitted here; `GET /v1/volatility/{ticker}/latest` carries it for the current tick. `meta` reports `effectiveStart`, `clamped`, and `historyMaxDays`. operationId: getVolatilityHistory parameters: - description: >- Ticker, case-insensitive. `GET /v1/indices` and `GET /v1/volatility` are the catalogs. example: MIDVOL in: path name: ticker required: true schema: type: string - description: Maximum points to return, newest first. 1 to 5000. example: 500 in: query name: limit required: false schema: default: 500 maximum: 5000 minimum: 1 type: integer - description: >- Include computations that did not clear the publication gates. Off by default: gated values are diagnostic, not published readings. in: query name: include_gated required: false schema: default: false type: boolean - description: >- Window start, ISO 8601. Optional, defaults to the earliest point in the trailing 90-day window. Older starts are clamped. example: '2026-08-24T00:00:00Z' in: query name: start required: false schema: anyOf: - format: date-time type: string - type: 'null' responses: '200': content: application/json: example: data: count: 2 points: - anchorFingerprint: >- 8fbefcee88e9d652648cfd9f28e1feb3ffb8068aa32a4e71304d0a43c282ecb5 attrDeltaHeadlinePts: -0.000022 bandHiPts: 35.636 bandLoPts: 35.4505 cfHeadlinePts: 35.9193 clockHomogeneityDisclosure: >- This value assumes Senate D · House D, Senate D · House R, Senate R · House D, Senate R · House R, Other release variance on a common election-night schedule. A Senate runoff, recount, or certification dispute would concentrate mass in a later window not modelled here; per-leg clocks are not yet separately estimated. clockVersion: clock-v1.0 compositionVersion: '1' devigVersion: devig-proportional-v1 effectiveN: 2.4605 fbvRLabel: remaining uncertainty (to resolution) fbvRPts: 77.0436 gateNames: - underround_flag headlinePts: 35.4977 methodologyVersion: fbv-v1.2 publicationState: published revision: 0 status: flagged t: '2026-08-31T13:59:35.599223' tenors: '1': pts: 6.7519 share: 0.00768 share_ci: null share_meta: ci_unavailable: true mixture: true '7': pts: 17.1047 share: 0.04929 share_ci: null share_meta: ci_unavailable: true mixture: true '30': pts: 35.4977 share: 0.212289 share_ci: null share_meta: ci_unavailable: true mixture: true tier: '1': historical-clock '7': historical-clock '30': historical-clock R: budget-implied units: probability points wTilde: 0.7419636 - anchorFingerprint: >- 8fbefcee88e9d652648cfd9f28e1feb3ffb8068aa32a4e71304d0a43c282ecb5 attrDeltaHeadlinePts: 0.000208 bandHiPts: 35.6359 bandLoPts: 35.4504 cfHeadlinePts: 35.9192 clockHomogeneityDisclosure: >- This value assumes Senate D · House D, Senate D · House R, Senate R · House D, Senate R · House R, Other release variance on a common election-night schedule. A Senate runoff, recount, or certification dispute would concentrate mass in a later window not modelled here; per-leg clocks are not yet separately estimated. clockVersion: clock-v1.0 compositionVersion: '1' devigVersion: devig-proportional-v1 effectiveN: 2.4605 fbvRLabel: remaining uncertainty (to resolution) fbvRPts: 77.0439 gateNames: - underround_flag headlinePts: 35.4977 methodologyVersion: fbv-v1.2 publicationState: published revision: 0 status: flagged t: '2026-08-31T13:54:35.559124' tenors: '1': pts: 6.7519 share: 0.00768 share_ci: null share_meta: ci_unavailable: true mixture: true '7': pts: 17.1047 share: 0.04929 share_ci: null share_meta: ci_unavailable: true mixture: true '30': pts: 35.4977 share: 0.212289 share_ci: null share_meta: ci_unavailable: true mixture: true tier: '1': historical-clock '7': historical-clock '30': historical-clock R: budget-implied units: probability points wTilde: 0.74197023 series: category: elections definitionLine: >- Belief Volatility is a standardized estimate of how much prediction-market probabilities are expected to move over a stated horizon. description: >- How much the 2026 U.S. midterms balance-of-power distribution is expected to move. gates: arbMinDepthUsd: 500 arbToleranceMin: 0.01 arbToleranceTicks: 1 depthFloorUsd: 500 devigTolerance: 0.000001 identityTolerance: 0.000001 impactBudgetPts: 1 overroundFlagHi: 1.04 overroundFlagLo: 0.995 pythagoreanTolerancePts2: 0.01 retireAfterDegradedTicks: 12 snapshotMaxAgeSeconds: 900 snapshotMaxSkewSeconds: 300 spreadToMidMax: 0.5 suspendFailingBudgetShare: 0.1 headlineTenorDays: 30 inceptionAt: '2026-08-06T00:01:51.828235Z' listed: true methodologyUrl: https://docs.beliefsystems.xyz/volatility/methodology name: Midterms Uncertainty Index productFamily: belief_volatility relatedIndexTickers: - MIDR26 - MIDD26 settlementDate: '2027-01-05' slug: midvol targetType: partition_composite tenorsDays: - 1 - 7 - 30 ticker: MIDVOL units: probability points windowStart: '2026-08-06T00:01:51.828235Z' meta: attribution: 'Source: Belief Systems (beliefsystems.xyz)' clamped: false effectiveStart: '2026-06-02T14:01:38.530876Z' generatedAt: '2026-08-31T14:01:38.550465Z' historyMaxDays: 90 license: https://beliefsystems.xyz/license termsUrl: https://beliefsystems.xyz/terms schema: $ref: '#/components/schemas/VolatilityHistoryResponse' description: Success. '401': content: application/json: example: error: code: invalid_api_key docsUrl: >- https://docs.beliefsystems.xyz/api-reference/limits#invalid-api-key message: >- This endpoint requires a Data API key. Create one free at https://beliefsystems.xyz/data ; programmatic or commercial licensing is at https://beliefsystems.xyz/license. requestId: 9f2c1ad4e6b74c0f8a3d5e1b7c904a26 schema: $ref: '#/components/schemas/Error' description: Missing or unresolvable API key. '404': content: application/json: example: error: code: not_found docsUrl: >- https://docs.beliefsystems.xyz/api-reference/limits#not-found message: >- No Belief index 'NOPE'. GET /v1/indices lists the published catalog. requestId: 9f2c1ad4e6b74c0f8a3d5e1b7c904a26 schema: $ref: '#/components/schemas/Error' description: No index or volatility series matches that ticker on this surface. '422': content: application/json: example: error: code: invalid_interval docsUrl: >- https://docs.beliefsystems.xyz/api-reference/limits#invalid-interval message: >- interval must be '1h' or '1d'. Full granularity is part of the licensed feed. requestId: 9f2c1ad4e6b74c0f8a3d5e1b7c904a26 schema: $ref: '#/components/schemas/Error' description: A parameter failed validation. '429': content: application/json: example: error: code: rate_limited docsUrl: >- https://docs.beliefsystems.xyz/api-reference/limits#rate-limited message: 'Rate limit exceeded: 60 requests per minute per key.' requestId: 9f2c1ad4e6b74c0f8a3d5e1b7c904a26 schema: $ref: '#/components/schemas/Error' description: >- Rate limited. Sleep for `Retry-After` seconds, which is exact on both windows. default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Error. Every /v1 failure uses this shape. x-codeSamples: - label: curl lang: curl source: >- curl -s "https://api.beliefsystems.xyz/v1/volatility/MIDVOL/history?limit=500" \ -H "Authorization: Bearer $BELIEF_API_KEY" - label: Python lang: python source: |- import os import requests resp = requests.get( "https://api.beliefsystems.xyz/v1/volatility/MIDVOL/history?limit=500", headers={"Authorization": f"Bearer {os.environ['BELIEF_API_KEY']}"}, timeout=10, ) resp.raise_for_status() payload = resp.json() print(payload["data"]) - label: JavaScript lang: javascript source: >- const res = await fetch("https://api.beliefsystems.xyz/v1/volatility/MIDVOL/history?limit=500", { headers: { Authorization: `Bearer ${process.env.BELIEF_API_KEY}` }, }); if (!res.ok) throw new Error(`Belief Systems API ${res.status}`); const { data, meta } = await res.json(); console.log(data); components: schemas: VolatilityHistoryResponse: properties: data: properties: count: type: integer points: description: Newest first. items: description: >- One published computation. Carries the headline fields; the per-leg panel is omitted on history. properties: anchorFingerprint: type: string attrDeltaHeadlinePts: type: number bandHiPts: type: number bandLoPts: type: number cfHeadlinePts: description: Counterfactual headline against the frozen anchor. type: number clockHomogeneityDisclosure: description: >- Standing disclosure about the timing assumption behind this value. type: string clockVersion: type: string compositionVersion: type: string devigVersion: type: string effectiveN: type: number fbvRLabel: type: string fbvRPts: description: >- Remaining uncertainty to resolution, in probability points. type: number gateNames: description: Names of gates that flagged on this tick. items: type: string type: array headlinePts: description: Headline value in probability points. type: number methodologyVersion: type: string publicationState: example: published type: string revision: type: integer status: example: flagged type: string t: description: >- Computation timestamp. UTC timestamp with microsecond precision. Serialized WITHOUT a `Z` suffix or offset, unlike timestamps elsewhere on this API. Treat it as UTC and attach the timezone yourself; a strict RFC 3339 parser will reject it. type: string tenors: additionalProperties: properties: pts: description: >- Expected movement over this horizon, in probability points. type: number share: description: >- Fraction of remaining uncertainty released by this horizon. type: - number - 'null' share_ci: description: Confidence interval on `share`, when available. items: type: number type: - array - 'null' share_meta: additionalProperties: true description: How `share` was derived. type: object type: object description: >- Published horizons, keyed by tenor in days as a string. `tenors["30"].pts` is the 30-day value, and equals `headlinePts` when 30 is the headline tenor. type: object tier: additionalProperties: true description: Estimation tier per tenor. type: object units: type: string wTilde: type: number type: object type: array series: description: >- The series definition. Identical across the catalog, latest, and history endpoints. properties: category: example: elections type: string definitionLine: description: >- The standing definition of Belief Volatility. Quote it when publishing a value. type: string description: description: One line on what the series measures. type: string gates: additionalProperties: true description: >- The publication tolerances in force for this series: overround bounds, depth floors, spread ceilings, and any partition consistency checks. Published so a value can be checked against the gates that admitted it. Field set varies by series target type. See the Belief Volatility methodology for what each gate tests. type: object headlineTenorDays: description: >- The tenor `headlinePts` refers to. Always name the tenor when quoting a value. example: 30 type: integer inceptionAt: format: date-time type: string listed: description: True when the series is published on the public surface. type: boolean methodologyUrl: format: uri type: string name: example: Midterms Uncertainty Index type: string productFamily: example: belief_volatility type: string relatedIndexTickers: description: Belief indices covering the same underlying events. items: type: string type: array settlementDate: description: Backstop settlement date, ISO 8601 date. type: - string - 'null' slug: description: URL segment for this series on beliefsystems.xyz. type: string targetType: description: The structure being measured. example: partition_composite type: string tenorsDays: description: Horizons published for this series, in days. example: - 1 - 7 - 30 items: type: integer type: array ticker: example: MIDVOL type: string units: description: The unit every `pts` value is quoted in. example: probability points type: string type: object windowStart: description: Series inception, for reference. format: date-time type: string type: object meta: properties: attribution: description: >- The attribution line required on anything you publish from this data. Reproduce it verbatim. example: 'Source: Belief Systems (beliefsystems.xyz)' type: string clamped: description: >- True when the requested start predated the free window. Read this before labeling a chart with the range you asked for. type: boolean effectiveStart: description: >- The start actually served, after clamping to the trailing window. format: date-time type: string generatedAt: description: >- When this response was generated. UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: string historyMaxDays: description: The trailing window in force, in days. Currently 90. example: 90 type: integer license: description: Terms covering production, redistribution, and commercial use. format: uri type: string termsUrl: description: Terms of Service. format: uri type: string required: - attribution - license - termsUrl - generatedAt - effectiveStart - clamped - historyMaxDays type: object required: - data - meta type: object Error: description: >- Every failure replaces `data` and `meta` with a single `error` object. Match on `code`, which is a stable contract. `message` is written for a person and may be reworded. properties: error: properties: code: description: Stable machine-readable error code. enum: - invalid_api_key - ip_rate_limited - rate_limited - daily_limit_reached - not_found - invalid_parameter - invalid_interval - invalid_window - method_not_allowed - internal_error - unavailable - error type: string docsUrl: description: Deep link to this code on the limits and errors page. format: uri type: string message: description: Human-readable explanation. Not a stable contract. type: string requestId: description: >- Correlation id, also returned as the X-Request-Id header. Quote it in support requests. type: string required: - code - message - docsUrl - requestId type: object required: - error title: Error type: object securitySchemes: bearerAuth: description: >- Your Data API key as a Bearer token: `Authorization: Bearer belief_live_...`. This is the canonical form. Keys belong on a server, never in a browser. scheme: bearer type: http apiKeyAuth: description: >- The same key sent as `X-API-Key` instead. Accepted everywhere the Bearer header is. Send one or the other, not both. in: header name: X-API-Key type: apiKey ````