> ## 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. # List graded markets > The family document and the current record for every graded market on the newest measurement day. A market whose inputs failed that day stays listed with its last publishable record, so its `asOf` is earlier; `dataStatus` and `lifecycleState` give its standing today. `universeDistribution` describes the whole graded universe, whatever `limit` you pass, so a letter can be read against how populated its band is. Markets below the coverage bar are not graded and do not appear: absence is not an `F`. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/grades 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, Belief Volatility series, and Market Grades (beta), 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: >- Market Grades are letter grades for the quality of individual prediction markets (liquidity and integrity), not for the likelihood of any outcome. The family is in beta: the methodology and the validation roadmap are published, and results are reported as they arrive. Join on `venue` and `marketId` together, and reproduce `disclosureLines` wherever you show a letter. name: Market Grades - 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/grades: get: tags: - Market Grades summary: List graded markets description: >- The family document and the current record for every graded market on the newest measurement day. A market whose inputs failed that day stays listed with its last publishable record, so its `asOf` is earlier; `dataStatus` and `lifecycleState` give its standing today. `universeDistribution` describes the whole graded universe, whatever `limit` you pass, so a letter can be read against how populated its band is. Markets below the coverage bar are not graded and do not appear: absence is not an `F`. operationId: listGrades parameters: - description: Maximum markets to return. 1 to 2000. example: 100 in: query name: limit required: false schema: default: 1000 maximum: 2000 minimum: 1 type: integer responses: '200': content: application/json: example: data: asOf: '2026-10-23T00:00:00.000000Z' count: 1 family: attribution: 'Source: Belief Systems (beliefsystems.xyz)' calibrationVersion: mg-cal-1.0 disclosureLines: - >- Market Grades measure market quality, not the likelihood of any outcome. - >- Market Grades are unsolicited: no graded party requests, pays for, or previews a grade. Belief Systems holds no positions in graded markets. - >- A grade is not a recommendation to buy, sell, or hold any position, and is not a substitute for a user's own assessment. familyName: Market Grades by Belief Systems listed: true methodologyUrl: https://docs.beliefsystems.xyz/grades/methodology methodologyVersion: mg-1.2 productFamily: market_grades seasonedObservedDays: 30 tierCaps: T0: C+ T1: B+ watchUnresolvedDays: 14 windowDays: 30 markets: - asOf: '2026-10-23T00:00:00.000000Z' calibrationVersion: mg-cal-1.0 caps: - binding: true cap_letter: D lowered_letter: false source: weakest_link - binding: false cap_letter: B+ lowered_letter: false source: evidence_tier computationStatus: candidate correction: null coverageClass: full coverageShare: 0.999885 dataStatus: ok disclosureLines: - >- Market Grades measure market quality, not the likelihood of any outcome. - >- Market Grades are unsolicited: no graded party requests, pays for, or previews a grade. Belief Systems holds no positions in graded markets. - >- A grade is not a recommendation to buy, sell, or hold any position, and is not a substitute for a user's own assessment. evidenceTier: T1 firstObserved: '2026-09-23T10:25:05.936852Z' gateFlags: [] grade: D gradeEpisodeId: >- polymarket:0x42945ea5657d6f6e77969a06661b29d6f6295083d1ef3479b42efd90647c9dfc:1 lastAction: actionType: grade_established asOf: '2026-10-23T00:00:00.000000Z' correctsActionId: null preLaunch: false publishedAt: '2026-10-23T01:39:00.519746Z' lastConfirmedAction: null lastFullData: '2026-10-23T00:00:00.000000Z' lifecycleState: active marketId: >- 0x42945ea5657d6f6e77969a06661b29d6f6295083d1ef3479b42efd90647c9dfc methodologyVersion: mg-1.2 observedDaysWindow: 30 pillarGrades: integrity: letter: B+ liquidity: letter: F preLaunch: false question: Will Ethereum reach $3,500 by December 31, 2026? revision: 0 stateRevision: 0 venue: polymarket watch: null window: - '2026-09-23T00:00:00.000000Z' - '2026-10-23T00:00:00.000000Z' productFamily: market_grades universeDistribution: asOf: '2026-10-23T00:00:00.000000Z' byBand: - band: A count: 2 share: 0.002395 - band: B count: 36 share: 0.043114 - band: C count: 126 share: 0.150898 - band: D count: 88 share: 0.105389 - band: F count: 303 share: 0.362874 byLetter: - count: 0 letter: A+ share: 0 - count: 0 letter: A share: 0 - count: 2 letter: A- share: 0.002395 - count: 7 letter: B+ share: 0.008383 - count: 11 letter: B share: 0.013174 - count: 18 letter: B- share: 0.021557 - count: 29 letter: C+ share: 0.034731 - count: 36 letter: C share: 0.043114 - count: 61 letter: C- share: 0.073054 - count: 88 letter: D share: 0.105389 - count: 303 letter: F share: 0.362874 notRated: count: 280 share: 0.335329 universeSize: 835 universeSize: 835 meta: attribution: 'Source: Belief Systems (beliefsystems.xyz)' generatedAt: '2026-10-23T15:49:14.582224Z' license: https://beliefsystems.xyz/license termsUrl: https://beliefsystems.xyz/terms schema: $ref: '#/components/schemas/GradesCatalogResponse' 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. '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/grades?limit=100" \ -H "Authorization: Bearer $BELIEF_API_KEY" - label: Python lang: python source: |- import os import requests resp = requests.get( "https://api.beliefsystems.xyz/v1/grades?limit=100", 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/grades?limit=100", { 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: GradesCatalogResponse: properties: data: properties: asOf: description: The measurement day served. format: date-time type: - string - 'null' count: description: Markets returned. type: integer family: description: >- The family document: versions, calibration quantities shown in copy, attribution, and the disclosure lines. properties: attribution: example: 'Source: Belief Systems (beliefsystems.xyz)' type: string calibrationVersion: type: string disclosureLines: items: type: string type: array familyName: type: string listed: description: True when the family is published. type: boolean methodologyUrl: format: uri type: string methodologyVersion: type: string productFamily: example: market_grades type: string seasonedObservedDays: description: Observed days a market needs before it can be rated. type: integer tierCaps: description: Best reachable letter for each lower evidence tier. properties: T0: type: string T1: type: string type: object watchUnresolvedDays: description: Days a watch can stay open before it lapses. type: integer windowDays: description: Measurement window length, in days. type: integer type: object markets: items: properties: asOf: description: >- Measurement day (window end). UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: string calibrationVersion: description: Calibration the record was computed under. example: mg-cal-1.0 type: string caps: description: >- Caps applied to the letter. Null wherever the letter is withheld. items: description: One cap applied to the letter. properties: binding: description: >- True when the cap is in force at or below the published letter. type: boolean cap_letter: description: >- The best letter the cap allows. Letter on the published scale, best to worst: `A+`, `A`, `A-`, `B+`, `B`, `B-`, `C+`, `C`, `C-`, `D`, `F`. type: string lowered_letter: description: >- True only when the cap actually lowered the letter it was applied to. type: boolean source: description: >- What imposed the cap: `evidence_tier` or `weakest_link`. type: string type: object type: - array - 'null' computationStatus: description: >- `candidate` (full evidence) or `data_limited` on every published record. type: string correction: description: >- Null unless a published correction changed the current letter. Then the grade is a labeled revision (shown as v2, v3, ...): `grade` is the corrected letter, and this block says when it was revised and what was first published. The original record stays on record (`revisions=all`). It returns to null when the letter next changes for a market reason. Cite the current letter and say it was revised; a correction is never an upgrade or downgrade. properties: noteUrl: description: The Governance Log note for the correction. format: uri type: string originalAsOf: description: '`asOf` of the record first published.' format: date-time type: string originalLetter: description: The letter first published for the corrected record. type: string reason: description: Why the grade was revised, in one plain sentence. maxLength: 200 type: string revisedAt: description: >- When the correction was published. UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: string version: description: >- 2 for the first correction of the letter, 3 for the second. minimum: 2 type: integer type: - object - 'null' coverageClass: description: Input coverage class, for example `full`. type: - string - 'null' coverageShare: description: >- Share of the window with usable order-book coverage, 0 to 1. type: - number - 'null' dataStatus: description: >- `ok`, `data-limited`, or `suspended-with-last-grade`. A suspension never erases a grade: while suspended, the current record shows the last grade with this marker, and `asOf` is the day that grade was measured. type: - string - 'null' disclosureLines: description: >- Three or more disclosure sentences: the family's three, plus any lines a venue's capability profile adds. Reproduce them wherever you show a letter. items: type: string type: array evidenceTier: description: >- `T2` (full), `T1`, or `T0`. Lower tiers cap the best reachable letter. type: - string - 'null' firstObserved: description: >- When the market was first observed. UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: - string - 'null' gateFlags: description: >- Names of the data gates that flagged this record. Empty when none did. items: type: string type: array grade: description: >- The grade of record. Letter on the published scale, best to worst: `A+`, `A`, `A-`, `B+`, `B`, `B-`, `C+`, `C`, `C-`, `D`, `F`. Null when the market is not rated (still seasoning, or terminal without a letter) or when the record predates the family's launch. type: - string - 'null' gradeEpisodeId: description: >- `venue:marketId:episode`. A new episode starts when a market's question materially changes. type: string lastAction: description: >- The market's latest rating action: its type and day, never its letters. properties: actionType: type: string asOf: format: date-time type: string correctsActionId: description: >- Non-null when this action is a correction. On a letter-setting row (upgrade, downgrade, first grade, rebaseline) read it as a revised grade, never as an upgrade or downgrade. When a correction's letter row and a linked Watch row share the newest day, this is the letter row. type: - string - 'null' preLaunch: type: boolean publishedAt: description: When the action was written to the archive. format: date-time type: string type: - object - 'null' lastConfirmedAction: description: >- `actionId` of the last confirmed letter change (an upgrade or downgrade), or null. A first grade is not one. type: - string - 'null' lastFullData: description: The last day with full input coverage. format: date-time type: - string - 'null' lifecycleState: description: >- Where the market is in its rating life: for example `active`, `provisional`, `nr_new`, `nr_data`, `nr_inactive`, `terminal`, `resolved`, `retired`. type: - string - 'null' marketId: description: >- The venue's own market identifier. Unique only within its venue, so always join on `venue` and `marketId` together. type: string methodologyVersion: description: Methodology the record was computed under. example: mg-1.2 type: string observedDaysWindow: description: Observed days in the window. type: - integer - 'null' pillarGrades: description: The two component grades, liquidity and integrity. properties: integrity: additionalProperties: true description: >- A component grade. `letter` is null wherever `grade` is null. When a letter is present on a current record, the object also carries `since` (start of the current letter run, UTC) and `trend` (`improving`, `stable`, or `deteriorating` over about 30 days). properties: letter: description: >- Letter on the published scale, best to worst: `A+`, `A`, `A-`, `B+`, `B`, `B-`, `C+`, `C`, `C-`, `D`, `F`. type: - string - 'null' type: object liquidity: additionalProperties: true description: >- A component grade. `letter` is null wherever `grade` is null. When a letter is present on a current record, the object also carries `since` (start of the current letter run, UTC) and `trend` (`improving`, `stable`, or `deteriorating` over about 30 days). properties: letter: description: >- Letter on the published scale, best to worst: `A+`, `A`, `A-`, `B+`, `B`, `B-`, `C+`, `C`, `C-`, `D`, `F`. type: - string - 'null' type: object type: object preLaunch: description: >- True for records measured before the family's launch. Their letters are withheld permanently. type: boolean question: description: >- The market's current question text, for display. Null if unknown. type: - string - 'null' revision: description: >- Correction marker for the computation. `0` as first published; corrections append, never overwrite. type: integer stateRevision: description: >- Correction marker for the lifecycle state rendered with this record. type: - integer - 'null' venue: description: Venue slug. example: polymarket type: string watch: description: An open watch, or null. properties: openedAsOf: description: >- UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: - string - 'null' value: description: '`negative` or `positive`.' type: string type: - object - 'null' window: description: The measurement window, `[start, end)`, in UTC. items: format: date-time type: string type: array type: object type: array productFamily: example: market_grades type: string universeDistribution: description: >- How the whole graded universe spreads across letters and bands, whatever `limit` you pass. properties: asOf: format: date-time type: - string - 'null' byBand: items: properties: band: type: string count: type: integer share: type: number type: object type: array byLetter: items: properties: count: type: integer letter: type: string share: type: number type: object type: array notRated: properties: count: type: integer share: type: number type: object universeSize: type: integer type: - object - 'null' universeSize: description: Markets in the graded universe on `asOf`. type: - integer - 'null' 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 generatedAt: description: >- When this response was generated. UTC timestamp with microsecond precision, `Z`-suffixed. format: date-time type: string 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 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.