Primary Source Commodities

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['events'], 'properties': {'events': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name', 'source', 'cadence', 'typical_time_et', 'next_hint', 'notes'], 'properties': {'id': {'type': 'string', 'description': 'Event id'}, 'name': {'type': 'string', 'description': 'Event name'}, 'notes': {'type': 'string', 'description': 'Additional notes'}, 'source': {'enum': ['EIA', 'USDA', 'CFTC'], 'type': 'string', 'description': 'Publishing agency'}, 'cadence': {'type': 'string', 'description': 'Release cadence'}, 'next_hint': {'type': 'string', 'description': 'Hint for the next expected release'}, 'typical_time_et': {'type': 'string', 'description': 'Typical release time in US/Eastern'}}}, 'description': 'Upcoming / recurring release events'}}}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['instruments'], 'properties': {'instruments': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name', 'sector', 'unit', 'primary_series_id', 'primary_source', 'freshness_class', 'license_tag'], 'properties': {'code': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'name': {'type': 'string', 'description': 'Display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'venue': {'type': 'string', 'description': 'Trading venue when known'}, 'sector': {'enum': ['energy', 'metals', 'ags', 'fx'], 'type': 'string', 'description': 'Sector grouping'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'primary_source': {'type': 'string', 'description': 'Primary source name, e.g. EIA or FRED'}, 'freshness_class': {'type': 'string', 'description': 'Expected freshness class'}, 'primary_series_id': {'type': 'string', 'description': 'Primary source series id'}, 'cot_commodity_hint': {'type': 'string', 'description': 'CFTC commodity hint when applicable'}}}, 'description': 'Instrument registry rows'}}}

{'type': 'object', 'required': ['sector'], 'properties': {'sector': {'enum': ['energy', 'metals', 'ags', 'all'], 'type': 'string', 'description': 'Sector for the decision pack. Use all to bundle every sector.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['generated_at', 'method'], 'properties': {'method': {'type': 'string', 'description': 'Deterministic method identifier'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Present for single-sector packs'}, 'sectors': {'type': 'object', 'description': 'Present when sector=all'}, 'signals': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'direction', 'rationale'], 'properties': {'id': {'type': 'string'}, 'direction': {'type': 'string'}, 'rationale': {'type': 'string'}}}, 'description': 'Directional signals with rationale'}, 'snapshot': {'type': 'object', 'required': ['sector', 'as_of', 'prices', 'freshness_note'], 'properties': {'cot': {'type': 'array', 'items': {'type': 'object'}, 'description': 'COT positioning rows when relevant'}, 'as_of': {'type': 'string', 'description': 'Snapshot as-of timestamp'}, 'crush': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'wasde': {'type': 'object', 'description': 'WASDE payload when relevant'}, 'prices': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Latest prices for the sector'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Sector covered by this snapshot'}, 'crack_321': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'inventory': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'Inventory points when relevant'}, 'export_sales': {'type': 'object', 'description': 'Export sales payload when relevant'}, 'crop_progress': {'type': 'object', 'description': 'Crop progress payload when relevant'}, 'freshness_note': {'type': 'string', 'description': 'Freshness summary note'}}}, 'disclaimer': {'type': 'string', 'description': 'Non-advice / methodology disclaimer'}, 'generated_at': {'type': 'string', 'description': 'ISO timestamp when the pack was generated'}, 'model_version': {'type': 'string', 'description': 'Always null for rule-based packs; reserved field'}}}

{'type': 'object', 'required': ['kind'], 'properties': {'kind': {'enum': ['wasde', 'crop_progress', 'export_sales', 'usgs'], 'type': 'string', 'description': 'Fundamentals report kind. Example: wasde for World Agricultural Supply and Demand Estimates.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'kind', 'as_of', 'observed_at', 'payload'], 'properties': {'id': {'type': 'string', 'description': 'Document id'}, 'kind': {'enum': ['wasde', 'crop_progress', 'export_sales', 'usgs'], 'type': 'string', 'description': 'Report kind echoed from the request'}, 'as_of': {'type': 'string', 'description': 'Report as-of date'}, 'payload': {'type': 'object', 'description': 'Kind-specific payload (quality, note, license_tag, freshness_class, and report fields)'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when retrieved'}}}

{'type': 'object', 'required': ['pair'], 'properties': {'pair': {'type': 'string', 'description': 'FX pair or series id. Example: EURUSD, USDCNY, DTWEXBGS.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}

{'type': 'object', 'properties': {'series': {'type': 'string', 'description': 'Optional EIA inventory series key. Omit to return all latest inventory rows. Example: crude_stocks.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'data': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'All latest inventory points when series is omitted'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average when series is provided'}, 'latest': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}, 'description': 'Latest point when a series key is provided'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change when series is provided'}, 'surprise_label': {'type': 'string', 'description': 'Surprise classification when series is provided'}}}

{'type': 'object', 'required': ['code'], 'properties': {'code': {'type': 'string', 'description': 'Instrument code from catalog.list. Example: CL, NG, GC, ZC.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['id', 'instrument', 'report_date', 'commodity_name', 'mm_long', 'mm_short', 'mm_net', 'mm_net_change', 'source_url', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'COT row id'}, 'mm_net': {'type': 'number', 'description': 'Managed-money net contracts'}, 'mm_long': {'type': 'number', 'description': 'Managed-money long contracts'}, 'mm_short': {'type': 'number', 'description': 'Managed-money short contracts'}, 'instrument': {'type': 'string', 'description': 'Instrument code'}, 'source_url': {'type': 'string', 'description': 'CFTC source URL'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'report_date': {'type': 'string', 'description': 'CFTC report date'}, 'mm_net_change': {'type': 'number', 'description': 'Week-over-week change in managed-money net'}, 'commodity_name': {'type': 'string', 'description': 'CFTC commodity name'}}}

{'type': 'object', 'required': ['code'], 'properties': {'code': {'type': 'string', 'description': 'Instrument code from catalog.list. Example: CL, GC, ZC.'}, 'limit': {'type': 'number', 'description': 'Number of historical points to return. Max 500, default 60.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['instrument', 'series_id', 'count', 'data'], 'properties': {'data': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Historical observations, newest first or as stored'}, 'count': {'type': 'number', 'description': 'Number of points returned'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code'}}}

{'type': 'object', 'required': ['code'], 'properties': {'code': {'type': 'string', 'description': 'Instrument code from catalog.list. Example: CL, GC, ZC.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}

{'type': 'object', 'required': ['sector'], 'properties': {'sector': {'enum': ['energy', 'metals', 'ags', 'all'], 'type': 'string', 'description': 'Sector to snapshot. Use all to receive energy, metals, and ags together.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['as_of'], 'properties': {'cot': {'type': 'array', 'items': {'type': 'object'}, 'description': 'COT rows when relevant'}, 'as_of': {'type': 'string', 'description': 'Snapshot as-of timestamp'}, 'crush': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'wasde': {'type': 'object', 'description': 'WASDE payload when relevant'}, 'prices': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Latest prices for the sector'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Present for single-sector responses'}, 'sectors': {'type': 'object', 'properties': {'ags': {'type': 'object', 'required': ['sector', 'as_of', 'prices', 'freshness_note'], 'properties': {'cot': {'type': 'array', 'items': {'type': 'object'}, 'description': 'COT positioning rows when relevant'}, 'as_of': {'type': 'string', 'description': 'Snapshot as-of timestamp'}, 'crush': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'wasde': {'type': 'object', 'description': 'WASDE payload when relevant'}, 'prices': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Latest prices for the sector'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Sector covered by this snapshot'}, 'crack_321': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'inventory': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'Inventory points when relevant'}, 'export_sales': {'type': 'object', 'description': 'Export sales payload when relevant'}, 'crop_progress': {'type': 'object', 'description': 'Crop progress payload when relevant'}, 'freshness_note': {'type': 'string', 'description': 'Freshness summary note'}}}, 'energy': {'type': 'object', 'required': ['sector', 'as_of', 'prices', 'freshness_note'], 'properties': {'cot': {'type': 'array', 'items': {'type': 'object'}, 'description': 'COT positioning rows when relevant'}, 'as_of': {'type': 'string', 'description': 'Snapshot as-of timestamp'}, 'crush': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'wasde': {'type': 'object', 'description': 'WASDE payload when relevant'}, 'prices': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Latest prices for the sector'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Sector covered by this snapshot'}, 'crack_321': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'inventory': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'Inventory points when relevant'}, 'export_sales': {'type': 'object', 'description': 'Export sales payload when relevant'}, 'crop_progress': {'type': 'object', 'description': 'Crop progress payload when relevant'}, 'freshness_note': {'type': 'string', 'description': 'Freshness summary note'}}}, 'metals': {'type': 'object', 'required': ['sector', 'as_of', 'prices', 'freshness_note'], 'properties': {'cot': {'type': 'array', 'items': {'type': 'object'}, 'description': 'COT positioning rows when relevant'}, 'as_of': {'type': 'string', 'description': 'Snapshot as-of timestamp'}, 'crush': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'wasde': {'type': 'object', 'description': 'WASDE payload when relevant'}, 'prices': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'description': 'Latest prices for the sector'}, 'sector': {'enum': ['energy', 'metals', 'ags'], 'type': 'string', 'description': 'Sector covered by this snapshot'}, 'crack_321': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'inventory': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'Inventory points when relevant'}, 'export_sales': {'type': 'object', 'description': 'Export sales payload when relevant'}, 'crop_progress': {'type': 'object', 'description': 'Crop progress payload when relevant'}, 'freshness_note': {'type': 'string', 'description': 'Freshness summary note'}}}}, 'description': 'Present when sector=all'}, 'crack_321': {'type': 'object', 'required': ['instrument', 'name', 'value', 'unit', 'as_of', 'observed_at', 'freshness_class', 'quality', 'derived', 'source', 'license_tag', 'provenance', 'series_id'], 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}, 'inventory': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'series_key', 'series_id', 'name', 'value', 'unit', 'as_of', 'observed_at'], 'properties': {'id': {'type': 'string', 'description': 'Inventory point id'}, 'name': {'type': 'string', 'description': 'Series display name'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'Report week as-of date'}, 'value': {'type': 'number', 'description': 'Latest inventory level'}, 'vs_5y': {'type': 'number', 'description': 'Deviation vs five-year average'}, 'avg_5y': {'type': 'number', 'description': 'Five-year average when known'}, 'series_id': {'type': 'string', 'description': 'EIA series id'}, 'prior_week': {'type': 'number', 'description': 'Prior-week level when known'}, 'series_key': {'type': 'string', 'description': 'Internal series key'}, 'wow_change': {'type': 'number', 'description': 'Week-over-week change'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}}}, 'description': 'Inventory rows when relevant'}, 'export_sales': {'type': 'object', 'description': 'Export sales when relevant'}, 'crop_progress': {'type': 'object', 'description': 'Crop progress when relevant'}, 'freshness_note': {'type': 'string', 'description': 'Freshness summary'}}}

{'type': 'object', 'required': ['type'], 'properties': {'root': {'type': 'string', 'description': 'Optional root symbol for calendar spreads. Example: CL. Ignored for crack/crush/basis.'}, 'type': {'enum': ['crack', 'crush', 'basis', 'calendar'], 'type': 'string', 'description': 'Spread type to compute. Example: crack for 3-2-1 gasoline/distillate crack.'}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Stable observation id'}, 'name': {'type': 'string', 'description': 'Human-readable instrument name'}, 'note': {'type': 'string', 'description': 'Explanation when unavailable or partially degraded'}, 'root': {'type': 'string', 'description': 'Calendar root when type=calendar'}, 'unit': {'type': 'string', 'description': 'Unit of measure'}, 'as_of': {'type': 'string', 'description': 'As-of date for the observation'}, 'value': {'type': 'number', 'description': 'Observed numeric value'}, 'inputs': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Input series ids when derived'}, 'source': {'type': 'object', 'required': ['name', 'series_id', 'url'], 'properties': {'url': {'type': 'string'}, 'name': {'type': 'string'}, 'series_id': {'type': 'string'}}, 'description': 'Primary source provenance'}, 'derived': {'type': 'boolean', 'description': 'True when value is derived'}, 'formula': {'type': 'string', 'description': 'Derivation formula when derived'}, 'quality': {'type': 'string', 'description': 'Data quality label'}, 'raw_hash': {'type': 'string', 'description': 'Hash of raw source payload'}, 'available': {'type': 'boolean', 'description': 'False when the spread cannot be computed'}, 'series_id': {'type': 'string', 'description': 'Underlying series id'}, 'instrument': {'type': 'string', 'description': 'Instrument code, e.g. CL'}, 'provenance': {'type': 'object', 'required': ['retrieved_at', 'cache_hit', 'cache_ttl_s'], 'properties': {'cache_hit': {'type': 'boolean'}, 'cache_ttl_s': {'type': 'number'}, 'retrieved_at': {'type': 'string'}}, 'description': 'Retrieval / cache provenance'}, 'license_tag': {'type': 'string', 'description': 'License / redistribution tag'}, 'observed_at': {'type': 'string', 'description': 'ISO timestamp when observed'}, 'legs_quality': {'type': 'array', 'items': {'type': 'object', 'required': ['instrument', 'quality'], 'properties': {'quality': {'type': 'string'}, 'instrument': {'type': 'string'}}}, 'description': 'Per-leg quality when inputs are mixed'}, 'freshness_class': {'type': 'string', 'description': 'Freshness class for the series'}}}