{"openapi":"3.1.0","info":{"title":"Gloom Datasets API","version":"1.0.0","description":"Specialised stored datasets on the Gloom API host. /v1 is the Gloom API's external, versioned namespace: dataset routes sit directly under it, and this product's catalog, account and reference routes under /v1/datasets. Gloom Datasets keys (gds_) and Gloom Pro keys are different keys for different APIs: each is refused by the other's routes. Runtime availability requires DATA_API_ENABLED. Pricing and plan allowances are working decisions; no billing is activated by this API."},"servers":[{"url":"https://api.gloom.sh"}],"security":[{"bearer":[]},{"apiKey":[]}],"x-plans":{"none":{"credits":0,"perMinute":0,"maxKeys":0},"basic":{"credits":150000,"perMinute":300,"maxKeys":5},"desk":{"credits":1000000,"perMinute":1200,"maxKeys":20},"enterprise":{"credits":null,"perMinute":null,"maxKeys":null}},"x-enterprise-default-limits":{"perMinute":6000,"maxKeys":100},"x-credit-call-types":{"lookup":1,"history":2,"search":2,"evidence":5,"bulk":25,"change":1},"x-bulk-plans":["basic","desk","enterprise"],"tags":[{"name":"Reference","description":"Public reference and estimates; no key required."},{"name":"Account","description":"Authenticated product account."},{"name":"awards","description":"Government awards"},{"name":"kpis-guidance","description":"KPIs and guidance"},{"name":"exec-pay","description":"Executive pay"},{"name":"events","description":"8-K events"},{"name":"cpi","description":"US consumer prices"},{"name":"energy-inventories","description":"EIA energy inventories"},{"name":"cot","description":"CFTC positioning"}],"paths":{"/v1/datasets":{"get":{"operationId":"datasets.list","tags":["Reference"],"summary":"Available datasets, starting credit cost and plans","security":[],"responses":{"200":{"description":"Public catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetCatalog"},"example":{"datasets":[{"id":"awards","name":"Government awards","status":"live","class":"sellable","classLabel":"Sellable","creditCost":4,"plans":["basic","desk","enterprise"]},{"id":"kpis-guidance","name":"KPIs and guidance","status":"live","class":"sellable","classLabel":"Sellable","creditCost":2,"plans":["basic","desk","enterprise"]},{"id":"exec-pay","name":"Executive pay","status":"live","class":"sellable","classLabel":"Sellable","creditCost":2,"plans":["basic","desk","enterprise"]},{"id":"events","name":"8-K events","status":"live","class":"sellable","classLabel":"Sellable","creditCost":2,"plans":["basic","desk","enterprise"]},{"id":"cpi","name":"US consumer prices","status":"live","class":"sellable","classLabel":"Sellable","creditCost":1,"plans":["basic","desk","enterprise"]},{"id":"energy-inventories","name":"EIA energy inventories","status":"live","class":"sellable","classLabel":"Sellable","creditCost":1,"plans":["basic","desk","enterprise"]},{"id":"cot","name":"CFTC positioning","status":"live","class":"sellable","classLabel":"Sellable","creditCost":1,"plans":["basic","desk","enterprise"]}]}}}}}}},"/v1/datasets/cost":{"get":{"operationId":"credits.estimate","tags":["Reference"],"summary":"Estimate a described call without spending credits","description":"Validates the described endpoint parameters. A quote does not authenticate or grant dataset access.","security":[],"parameters":[{"name":"endpoint","in":"query","required":true,"description":"Catalog endpoint ID. Supply that call's path and query parameters in this query.","schema":{"type":"string","enum":["cpi.board","energy.inventories","cot.board","cot.contract","awards.list","awards.detail","kpis.company","guidance.company","exec-pay.list","exec-pay.year","events.list"]}},{"name":"report","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["legacy","disaggregated"],"default":"legacy"}},{"name":"traderClass","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["noncommercial","commercial","nonreportable","producer","swap","managed-money","other-reportable"],"description":"Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable."}},{"name":"contractCode","in":"query","required":false,"schema":{"type":"string","minLength":6,"maxLength":6,"pattern":"^[0-9A-Za-z]{5}[0-9A-Za-z+]$","description":"Six-character CFTC market code; normalized to uppercase."}},{"name":"ticker","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"jurisdiction","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[A-Za-z]{2,3}$"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[A-Za-z]{3}$"}},{"name":"agency","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"sector","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_-]{1,64}$"}},{"name":"parentId","in":"query","required":false,"schema":{"type":"string","minLength":40,"maxLength":40,"pattern":"^[a-f0-9]{40}$"}},{"name":"awardType","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["prime","subaward","modification","notice"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"integer","minimum":2000,"maximum":2100}},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"minAmount","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":31,"pattern":"^\\d{1,24}(?:\\.\\d{1,6})?$","description":"Nonnegative decimal amount, supplied as a string to preserve precision."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"id","in":"query","required":false,"schema":{"type":"string","minLength":40,"maxLength":40,"pattern":"^[a-f0-9]{40}$"}},{"name":"revisionsCursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S"}},{"name":"symbol","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9_]{1,80}$"}},{"name":"basis","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["reported","adjusted","constant_currency","organic"]}},{"name":"asOf","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2100}}],"responses":{"200":{"description":"Credit estimate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditEstimate"}}}},"400":{"$ref":"#/components/responses/Error400"}}}},"/v1/datasets/openapi.json":{"get":{"operationId":"openapi.get","tags":["Reference"],"summary":"OpenAPI 3.1 document","security":[],"responses":{"200":{"description":"This API document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/datasets/account":{"get":{"operationId":"account.get","tags":["Account"],"summary":"Account plan, status, current credit period and limits","x-credit-cost":0,"x-plans":["basic","desk","enterprise"],"responses":{"200":{"description":"The key's account. The balance is authoritative.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/datasets/usage":{"get":{"operationId":"usage.get","tags":["Account"],"summary":"Account plan, current credit period and per-dataset usage","x-credit-cost":0,"x-plans":["basic","desk","enterprise"],"responses":{"200":{"description":"Account balance and period usage. Usage rows are buffered; the balance is authoritative.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/datasets/awards/sample":{"get":{"operationId":"awards.sample","tags":["awards"],"summary":"Static Government awards sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"generatedAt":"2026-09-30T12:00:00.000Z","asOf":"2026-09-30T12:00:00.000Z","status":"available","access":"preview","rows":[{"id":"1111111111111111111111111111111111111111","revisionId":"4444444444444444444444444444444444444444","source":"usaspending","sourceAwardId":"ILLUSTRATIVE-1","jurisdiction":"US","awardType":"prime","title":"Illustrative procurement 1","awardDate":"2026-09-30","currency":"USD","obligatedAmount":"100","recipient":{"name":"Illustrative Company"},"agency":{"name":"Illustrative Agency"},"sourceUrl":"https://example.invalid/awards/1","observedAt":"2026-09-30T12:00:00.000Z","entity":null,"revenueComparison":null},{"id":"2222222222222222222222222222222222222222","revisionId":"5555555555555555555555555555555555555555","source":"usaspending","sourceAwardId":"ILLUSTRATIVE-2","jurisdiction":"US","awardType":"prime","title":"Illustrative procurement 2","awardDate":"2026-09-30","currency":"USD","obligatedAmount":"200","recipient":{"name":"Illustrative Company"},"agency":{"name":"Illustrative Agency"},"sourceUrl":"https://example.invalid/awards/2","observedAt":"2026-09-30T12:00:00.000Z","entity":null,"revenueComparison":null},{"id":"3333333333333333333333333333333333333333","revisionId":"6666666666666666666666666666666666666666","source":"usaspending","sourceAwardId":"ILLUSTRATIVE-3","jurisdiction":"US","awardType":"prime","title":"Illustrative procurement 3","awardDate":"2026-09-30","currency":"USD","obligatedAmount":"300","recipient":{"name":"Illustrative Company"},"agency":{"name":"Illustrative Agency"},"sourceUrl":"https://example.invalid/awards/3","observedAt":"2026-09-30T12:00:00.000Z","entity":null,"revenueComparison":null}],"nextCursor":null,"agencies":[],"sectors":[],"leaders":[],"history":[],"alerts":[],"sources":[],"coverage":[],"gaps":[],"locked":true},"meta":{"dataset":"awards","asOf":null,"source":[{"id":"usaspending","attribution":"USAspending.gov","licence":"U.S. public government data"},{"id":"ted","attribution":"European Union TED","licence":"Reuse with attribution"},{"id":"uk-contracts","attribution":"UK Contracts Finder and Find a Tender","licence":"Open Government Licence v3"},{"id":"canada-contracts","attribution":"Government of Canada","licence":"Open Government Licence Canada"},{"id":"gleif","attribution":"GLEIF","licence":"CC0"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/kpis-guidance/sample":{"get":{"operationId":"kpis-guidance.sample","tags":["kpis-guidance"],"summary":"Static KPIs and guidance sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"symbol":"ILLUSTRATIVE","status":"available","asOf":"2026-09-30T12:00:00.000Z","coverage":{"country":"US","languages":["en"],"documents":1,"observations":3,"guidance":0,"firstPeriod":"2026-09-30","lastPeriod":"2026-09-30","lastPublishedAt":"2026-09-30T12:00:00.000Z","sourceKinds":["filing"],"conflicts":0},"series":[{"key":"revenue","metric":{"id":"revenue","name":"Illustrative revenue","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"unit":"count","currency":null,"basis":"reported","dimensions":{},"latest":{"id":"illustrative-fact-1","symbol":"ILLUSTRATIVE","metricId":"revenue","metric":{"id":"revenue","name":"Illustrative revenue","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":100,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"revenue","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-1","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE revenue was 100.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]},"observations":[{"id":"illustrative-fact-1","symbol":"ILLUSTRATIVE","metricId":"revenue","metric":{"id":"revenue","name":"Illustrative revenue","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":100,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"revenue","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-1","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE revenue was 100.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]}]},{"key":"volume","metric":{"id":"volume","name":"Illustrative volume","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"unit":"count","currency":null,"basis":"reported","dimensions":{},"latest":{"id":"illustrative-fact-2","symbol":"ILLUSTRATIVE","metricId":"volume","metric":{"id":"volume","name":"Illustrative volume","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":200,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"volume","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-2","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE volume was 200.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]},"observations":[{"id":"illustrative-fact-2","symbol":"ILLUSTRATIVE","metricId":"volume","metric":{"id":"volume","name":"Illustrative volume","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":200,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"volume","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-2","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE volume was 200.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]}]},{"key":"subscribers","metric":{"id":"subscribers","name":"Illustrative subscribers","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"unit":"count","currency":null,"basis":"reported","dimensions":{},"latest":{"id":"illustrative-fact-3","symbol":"ILLUSTRATIVE","metricId":"subscribers","metric":{"id":"subscribers","name":"Illustrative subscribers","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":300,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"subscribers","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-3","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE subscribers was 300.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]},"observations":[{"id":"illustrative-fact-3","symbol":"ILLUSTRATIVE","metricId":"subscribers","metric":{"id":"subscribers","name":"Illustrative subscribers","sector":"general","unit":"count","definition":"Illustrative metric","aliases":{},"favorable":"higher"},"period":{"start":"2026-07-01","end":"2026-09-30","kind":"quarter","fiscalYear":2026,"fiscalQuarter":3,"label":"Q3 2026"},"value":300,"unit":"count","currency":null,"basis":"reported","dimensions":{},"confidence":1,"seriesKey":"subscribers","asOf":"2026-09-30T12:00:00.000Z","supersedesId":null,"revision":1,"current":true,"conflict":false,"evidence":[{"id":"illustrative-evidence-3","documentId":"illustrative-document","sourceId":"illustrative-filing","sourceKind":"filing","url":"https://example.invalid/illustrative-filing","title":"ILLUSTRATIVE filing","publishedAt":"2026-09-30T12:00:00.000Z","country":"US","language":"en","quote":"ILLUSTRATIVE subscribers was 300.","quoteOffset":0,"quoteSourceLength":100,"quoteMatchMode":"exact","confidence":1}]}]}],"revisions":[],"dictionary":[],"access":"preview","lockedRows":0,"totalRows":3,"truncated":false,"previewRows":3,"methodology":"ILLUSTRATIVE company-disclosed operating metrics with source evidence."},"meta":{"dataset":"kpis-guidance","asOf":null,"source":[{"id":"sec-edgar","attribution":"U.S. Securities and Exchange Commission and the filing issuer","licence":"Public SEC filings; preserve filing attribution and fair-access limits"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/exec-pay/sample":{"get":{"operationId":"exec-pay.sample","tags":["exec-pay"],"summary":"Static Executive pay sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"proxies":[{"id":"illustrative-proxy-0","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"proxyYear":2026,"fiscalYear":2025,"fiscalYearLabel":"2025","filedAt":"2026-03-30T12:00:00.000Z","meetingDate":null,"updatedAt":"2026-09-30T12:00:00.000Z","ceoName":"Illustrative Executive","ceoTitle":"Chief Executive Officer","ceoTotal":1000000,"ceoPriorYearTotal":null,"payRatio":null,"medianEmployeePay":null},{"id":"illustrative-proxy-1","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"proxyYear":2025,"fiscalYear":2024,"fiscalYearLabel":"2024","filedAt":"2025-03-30T12:00:00.000Z","meetingDate":null,"updatedAt":"2026-09-30T12:00:00.000Z","ceoName":"Illustrative Executive","ceoTitle":"Chief Executive Officer","ceoTotal":1000000,"ceoPriorYearTotal":null,"payRatio":null,"medianEmployeePay":null},{"id":"illustrative-proxy-2","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"proxyYear":2024,"fiscalYear":2023,"fiscalYearLabel":"2023","filedAt":"2024-03-30T12:00:00.000Z","meetingDate":null,"updatedAt":"2026-09-30T12:00:00.000Z","ceoName":"Illustrative Executive","ceoTitle":"Chief Executive Officer","ceoTotal":1000000,"ceoPriorYearTotal":null,"payRatio":null,"medianEmployeePay":null}]},"meta":{"dataset":"exec-pay","asOf":null,"source":[{"id":"sec-edgar","attribution":"U.S. Securities and Exchange Commission and the filing issuer","licence":"Public SEC filings; preserve filing attribution and fair-access limits"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/events/sample":{"get":{"operationId":"events.sample","tags":["events"],"summary":"Static 8-K events sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"events":[{"id":"illustrative-event-1","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"filedAt":"2026-09-30T12:00:00.000Z","filingDate":"2026-09-30","form":"8-K","docUrl":"https://example.invalid/events/1","items":["5.02"],"labels":["Director or officer changes"],"kinds":["people"],"material":true,"headline":"ILLUSTRATIVE officer change 1","summary":null,"people":[],"read":false},{"id":"illustrative-event-2","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"filedAt":"2026-09-30T12:00:00.000Z","filingDate":"2026-09-30","form":"8-K","docUrl":"https://example.invalid/events/2","items":["5.02"],"labels":["Director or officer changes"],"kinds":["people"],"material":true,"headline":"ILLUSTRATIVE officer change 2","summary":null,"people":[],"read":false},{"id":"illustrative-event-3","ticker":"ILLUSTRATIVE","company":{"ticker":"ILLUSTRATIVE","cik":null,"name":"Illustrative Company","shortName":"Illustrative Company"},"filedAt":"2026-09-30T12:00:00.000Z","filingDate":"2026-09-30","form":"8-K","docUrl":"https://example.invalid/events/3","items":["5.02"],"labels":["Director or officer changes"],"kinds":["people"],"material":true,"headline":"ILLUSTRATIVE officer change 3","summary":null,"people":[],"read":false}]},"meta":{"dataset":"events","asOf":null,"source":[{"id":"sec-edgar","attribution":"U.S. Securities and Exchange Commission and the filing issuer","licence":"Public SEC filings; preserve filing attribution and fair-access limits"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/cpi/sample":{"get":{"operationId":"cpi.sample","tags":["cpi"],"summary":"Static US consumer prices sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"source":"BLS","generatedAt":"2026-09-30T12:00:00.000Z","retrievedAt":"2026-09-30T12:00:00.000Z","status":"partial","gaps":["ILLUSTRATIVE sample only"],"release":{"period":"2026-08","releasedAt":null,"weightsPeriod":null,"nextPeriod":null,"nextReleaseAt":null},"rows":[{"id":"all-items","code":"SA0","label":"All items","depth":0,"parent":null,"pinned":true,"derived":false,"weight":null,"change":0.1,"annualized3m":null,"annualized6m":null,"yoy":2.1,"contribution":null,"contributionYoy":null,"read":null,"history":[["2026-08",0.1,2.1]]},{"id":"core","code":"SA0L1E","label":"All items less food and energy","depth":0,"parent":null,"pinned":true,"derived":false,"weight":null,"change":0.2,"annualized3m":null,"annualized6m":null,"yoy":2.2,"contribution":null,"contributionYoy":null,"read":null,"history":[["2026-08",0.2,2.2]]},{"id":"shelter","code":"SAH1","label":"Shelter","depth":0,"parent":null,"pinned":true,"derived":false,"weight":null,"change":0.3,"annualized3m":null,"annualized6m":null,"yoy":2.3,"contribution":null,"contributionYoy":null,"read":null,"history":[["2026-08",0.3,2.3]]}]},"meta":{"dataset":"cpi","asOf":null,"source":[{"id":"bls-cpi","attribution":"U.S. Bureau of Labor Statistics","licence":"Public domain; retain BLS disclaimer"},{"id":"fred-bls-mirror","attribution":"Federal Reserve Bank of St. Louis, original source BLS","licence":"BLS-origin CPI mirror only, not a general FRED resale grant"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations.","disclaimer":"BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov. Derived calculations are Gloom's, not BLS figures."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/energy-inventories/sample":{"get":{"operationId":"energy-inventories.sample","tags":["energy-inventories"],"summary":"Static EIA energy inventories sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"source":"EIA","generatedAt":"2026-09-30T12:00:00.000Z","status":"partial","gaps":["ILLUSTRATIVE sample only"],"reports":[{"id":"petroleum","weekEnding":"2026-09-25","releasedAt":null,"releaseHoliday":null,"nextWeekEnding":null,"nextReleaseAt":null,"nextReleaseHoliday":null}],"series":[{"id":"crude-commercial","key":"WCESTUS1","report":"petroleum","tab":"crude","label":"Commercial crude oil","unit":"kb","weekEnding":"2026-09-25","value":100,"previousWeekEnding":"2026-09-18","weekChange":1,"yearAgo":null,"fiveYear":null,"read":null,"seasonal":null},{"id":"gasoline","key":"WGTSTUS1","report":"petroleum","tab":"products","label":"Motor gasoline","unit":"kb","weekEnding":"2026-09-25","value":200,"previousWeekEnding":"2026-09-18","weekChange":2,"yearAgo":null,"fiveYear":null,"read":null,"seasonal":null},{"id":"distillate","key":"WDISTUS1","report":"petroleum","tab":"products","label":"Distillate fuel oil","unit":"kb","weekEnding":"2026-09-25","value":300,"previousWeekEnding":"2026-09-18","weekChange":3,"yearAgo":null,"fiveYear":null,"read":null,"seasonal":null}]},"meta":{"dataset":"energy-inventories","asOf":null,"source":[{"id":"eia-inventories","attribution":"U.S. Energy Information Administration","licence":"Public domain"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/datasets/cot/sample":{"get":{"operationId":"cot.sample","tags":["cot"],"summary":"Static CFTC positioning sample","description":"Three illustrative rows, clearly marked in metadata. Limited to 30 sample requests per IP per hour.","security":[],"x-credit-cost":0,"responses":{"200":{"description":"Static illustrative fixture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"},"example":{"data":{"source":"CFTC","scope":"futures-only","reportFamily":"legacy","generatedAt":"2026-09-30T12:00:00.000Z","asOf":"2026-09-29","fetchedAt":"2026-09-30T12:00:00.000Z","publishedAt":null,"status":"partial","gaps":["ILLUSTRATIVE sample only"],"classes":[{"id":"noncommercial","label":"Noncommercial"}],"traderClass":"noncommercial","rows":[{"contractCode":"000001","marketName":"ILLUSTRATIVE contract 1","exchangeCode":"ILLUSTRATIVE","commodityCode":"ILLUSTRATIVE","reportDate":"2026-09-29","openInterest":1000,"position":{"id":"noncommercial","label":"Noncommercial","long":300,"short":200,"spreading":0,"net":100,"netPercentOfOpenInterest":10,"weeklyChange":null,"previousReportDate":null,"percentile1Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null},"percentile3Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null}},"status":"available"},{"contractCode":"000002","marketName":"ILLUSTRATIVE contract 2","exchangeCode":"ILLUSTRATIVE","commodityCode":"ILLUSTRATIVE","reportDate":"2026-09-29","openInterest":1000,"position":{"id":"noncommercial","label":"Noncommercial","long":300,"short":200,"spreading":0,"net":100,"netPercentOfOpenInterest":10,"weeklyChange":null,"previousReportDate":null,"percentile1Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null},"percentile3Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null}},"status":"available"},{"contractCode":"000003","marketName":"ILLUSTRATIVE contract 3","exchangeCode":"ILLUSTRATIVE","commodityCode":"ILLUSTRATIVE","reportDate":"2026-09-29","openInterest":1000,"position":{"id":"noncommercial","label":"Noncommercial","long":300,"short":200,"spreading":0,"net":100,"netPercentOfOpenInterest":10,"weeklyChange":null,"previousReportDate":null,"percentile1Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null},"percentile3Y":{"value":null,"rank":null,"sampleCount":0,"windowStart":"2025-09-29","windowEnd":"2026-09-29","historyStart":null,"historyEnd":null,"completeWindow":false,"min":null,"max":null,"mean":null}},"status":"available"}]},"meta":{"dataset":"cot","asOf":null,"source":[{"id":"cftc-cot","attribution":"Commodity Futures Trading Commission","licence":"Public government files"}],"historyStarts":null,"coverage":null,"lastUpdated":null,"sample":true,"note":"ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."}}}}},"429":{"$ref":"#/components/responses/Error429"}}}},"/v1/macro/cpi":{"get":{"operationId":"cpi.board","tags":["cpi"],"summary":"US CPI components, weights and contributions","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[],"x-dataset":"cpi","x-credit-cost":1,"x-credit-call-type":"lookup","x-credit-multiplier":1,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/cpi/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/energy/inventories":{"get":{"operationId":"energy.inventories","tags":["energy-inventories"],"summary":"EIA petroleum and gas inventories","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[],"x-dataset":"energy-inventories","x-credit-cost":1,"x-credit-call-type":"lookup","x-credit-multiplier":1,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/energy-inventories/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/cftc/cot":{"get":{"operationId":"cot.board","tags":["cot"],"summary":"CFTC positioning by contract","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"report","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["legacy","disaggregated"],"default":"legacy"}},{"name":"traderClass","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["noncommercial","commercial","nonreportable","producer","swap","managed-money","other-reportable"],"description":"Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable."}}],"x-dataset":"cot","x-credit-cost":1,"x-credit-call-type":"lookup","x-credit-multiplier":1,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/cot/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/cftc/cot/contracts/{contractCode}":{"get":{"operationId":"cot.contract","tags":["cot"],"summary":"CFTC contract positioning history","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"contractCode","in":"path","required":true,"schema":{"type":"string","minLength":6,"maxLength":6,"pattern":"^[0-9A-Za-z]{5}[0-9A-Za-z+]$","description":"Six-character CFTC market code; normalized to uppercase."}},{"name":"report","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["legacy","disaggregated"],"default":"legacy"}},{"name":"traderClass","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["noncommercial","commercial","nonreportable","producer","swap","managed-money","other-reportable"],"description":"Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable."}}],"x-dataset":"cot","x-credit-cost":2,"x-credit-call-type":"history","x-credit-multiplier":1,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/cot/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/awards":{"get":{"operationId":"awards.list","tags":["awards"],"summary":"Government awards with source evidence","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"jurisdiction","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[A-Za-z]{2,3}$"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[A-Za-z]{3}$"}},{"name":"agency","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"sector","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_-]{1,64}$"}},{"name":"parentId","in":"query","required":false,"schema":{"type":"string","minLength":40,"maxLength":40,"pattern":"^[a-f0-9]{40}$"}},{"name":"awardType","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["prime","subaward","modification","notice"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"integer","minimum":2000,"maximum":2100}},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"}},{"name":"minAmount","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":31,"pattern":"^\\d{1,24}(?:\\.\\d{1,6})?$","description":"Nonnegative decimal amount, supplied as a string to preserve precision."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"x-dataset":"awards","x-credit-cost":4,"x-credit-call-type":"search","x-credit-multiplier":2,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/awards/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/awards/{id}":{"get":{"operationId":"awards.detail","tags":["awards"],"summary":"Award evidence and revisions","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":40,"maxLength":40,"pattern":"^[a-f0-9]{40}$"}},{"name":"revisionsCursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S"}}],"x-dataset":"awards","x-credit-cost":10,"x-credit-call-type":"evidence","x-credit-multiplier":2,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/awards/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/kpis/{symbol}":{"get":{"operationId":"kpis.company","tags":["kpis-guidance"],"summary":"Cited filing operating metrics","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. A from or to parameter selects the history price; asOf requires Basic or above. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9_]{1,80}$"}},{"name":"basis","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["reported","adjusted","constant_currency","organic"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"asOf","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}}],"x-dataset":"kpis-guidance","x-credit-cost":2,"x-credit-call-type":"lookup","x-credit-multiplier":2,"x-credit-cost-history":4,"x-asof-plans":["basic","desk","enterprise"],"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/kpis-guidance/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/guidance/{symbol}":{"get":{"operationId":"guidance.company","tags":["kpis-guidance"],"summary":"Filing guidance ranges and revisions","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. A from or to parameter selects the history price; asOf requires Basic or above. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9_]{1,80}$"}},{"name":"basis","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":1024,"pattern":"\\S","enum":["reported","adjusted","constant_currency","organic"]}},{"name":"from","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}},{"name":"asOf","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","format":"date","description":"Valid calendar date (YYYY-MM-DD). from must be on or before to."}}],"x-dataset":"kpis-guidance","x-credit-cost":2,"x-credit-call-type":"lookup","x-credit-multiplier":2,"x-credit-cost-history":4,"x-asof-plans":["basic","desk","enterprise"],"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/kpis-guidance/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/exec-pay/{symbol}":{"get":{"operationId":"exec-pay.list","tags":["exec-pay"],"summary":"Available executive compensation filings","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}}],"x-dataset":"exec-pay","x-credit-cost":2,"x-credit-call-type":"lookup","x-credit-multiplier":2,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/exec-pay/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/exec-pay/{symbol}/{year}":{"get":{"operationId":"exec-pay.year","tags":["exec-pay"],"summary":"Executive compensation for a filing year","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"year","in":"path","required":true,"schema":{"type":"integer","minimum":1900,"maximum":2100}}],"x-dataset":"exec-pay","x-credit-cost":10,"x-credit-call-type":"evidence","x-credit-multiplier":2,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/exec-pay/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}},"/v1/events/{symbol}":{"get":{"operationId":"events.list","tags":["events"],"summary":"Item-classified SEC 8-K events","description":"Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[A-Za-z0-9.:-]{1,32}$","description":"Company symbol; normalized to uppercase."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"x-dataset":"events","x-credit-cost":2,"x-credit-call-type":"search","x-credit-multiplier":1,"x-plans":["basic","desk","enterprise"],"x-sample-url":"/v1/datasets/events/sample","responses":{"200":{"description":"Stored dataset response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"},"503":{"$ref":"#/components/responses/Error503"}}}}},"components":{"responses":{"Error400":{"description":"invalid_params: request parameters failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"Error401":{"description":"missing_key, invalid_key or wrong_key: a product key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"Error402":{"description":"plan_required or dataset_not_included: the key's account has no plan, or its plan does not include this dataset or depth.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"Error403":{"description":"key_disabled: this key has been disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"Error404":{"description":"not_found: the requested stored award or compensation filing was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}}}},"Error429":{"description":"rate_limited or credits_exhausted: wait before retrying or upgrade the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the request may be retried.","schema":{"type":"integer","minimum":1}}}},"Error503":{"description":"unavailable: stored data or an internal dependency is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Credits-Cost":{"description":"Credits charged for this request. A refund is attempted when the handler fails with a server error.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the account's current period.","schema":{"type":"integer","minimum":0}},"X-Plan":{"schema":{"type":"string","enum":["basic","desk","enterprise"]}},"X-Request-Id":{"schema":{"type":"string"}},"Retry-After":{"description":"Seconds until the request may be retried.","schema":{"type":"integer","minimum":1}}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Gloom Datasets key, starting gds_. Gloom Pro and News API keys are refused with wrong_key."},"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["missing_key","invalid_key","wrong_key","key_disabled","plan_required","not_found","rate_limited","credits_exhausted","dataset_not_included","invalid_params","unavailable"]},"message":{"type":"string"}}},"DatasetResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"description":"Dataset-specific stored records or board. See the sample endpoint for representative field names."},"meta":{"type":"object","required":["dataset","asOf","source","historyStarts","coverage","lastUpdated"],"properties":{"dataset":{"type":"string","enum":["awards","kpis-guidance","exec-pay","events","cpi","energy-inventories","cot"]},"asOf":{"type":["string","null"]},"source":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"attribution":{"type":"string"},"licence":{"type":"string"}}}},"historyStarts":{"type":["string","null"],"description":"Earliest stored history when established by the service; otherwise null."},"coverage":{"description":"Service-established coverage; null when unavailable."},"lastUpdated":{"type":["string","null"]},"sample":{"type":"boolean"},"note":{"type":"string"}}}}},"DatasetCatalog":{"type":"object","required":["datasets"],"properties":{"datasets":{"type":"array","items":{"type":"object","required":["id","name","status","class","classLabel","creditCost","plans"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["live"]},"class":{"type":"string","enum":["sellable"]},"classLabel":{"type":"string"},"creditCost":{"type":"integer","minimum":1},"plans":{"type":"array","items":{"type":"string","enum":["basic","desk","enterprise"]}}}}}}},"CreditEstimate":{"type":"object","required":["endpoint","dataset","credits","callType","base","multiplier"],"properties":{"endpoint":{"type":"string"},"dataset":{"type":"string"},"credits":{"type":"integer","minimum":1},"callType":{"type":"string","enum":["lookup","history","search","evidence","bulk","change"]},"base":{"type":"integer","minimum":1},"multiplier":{"type":"integer","enum":[1,2,4]}}},"Account":{"type":"object","required":["plan","status","period","credits","limits"],"description":"The account's plan and status, its credit period with authoritative credits used and remaining, and the rate and key limits applied to it. Enterprise limits are set by contract; until then an Enterprise account gets 6,000 credits a minute for each key and 100 keys.","properties":{"plan":{"type":"string","enum":["basic","desk","enterprise"]},"status":{"type":"string","enum":["active","suspended","canceled"]},"period":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"credits":{"type":"object","required":["included","used","remaining"],"properties":{"included":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}}},"limits":{"type":"object","required":["perMinute","maxKeys"],"properties":{"perMinute":{"type":"integer","minimum":0,"description":"Credits a minute, for each key."},"maxKeys":{"type":"integer","minimum":0}}}}},"Usage":{"type":"object","required":["plan","status","period","credits","datasets"],"description":"The account's plan, credit period, authoritative credits used and remaining, and buffered per-dataset usage.","properties":{"plan":{"type":"string","enum":["basic","desk","enterprise"]},"status":{"type":"string","enum":["active","suspended","canceled"]},"credits":{"type":"object","required":["included","used","remaining"],"properties":{"included":{"type":"integer","minimum":0},"used":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}}},"period":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"datasets":{"type":"array","items":{"type":"object","required":["dataset","requests","credits","rows","errors"],"properties":{"dataset":{"type":"string"},"requests":{"type":"integer","minimum":0},"credits":{"type":"integer","minimum":0},"rows":{"type":"integer","minimum":0},"errors":{"type":"integer","minimum":0}}}}}}}}}