> ## Documentation Index > Fetch the complete documentation index at: https://docs.engrate.io/llms.txt > Use this file to discover all available pages before exploring further. # List Aggregate Allocations > List aggregate allocations timeseries data matching the provided filters. Note that this can return multiple values per ISP for the same dimensions, as the underlying storage is append-only. You tell those rows apart by looking at the [finality](/api-reference/allocations/models/finality) and known_at. If you are training a model this allows you to train the model on data that was known at the time the model will be running, avoiding training it on data that is "from the future". If you are doing controlling, this allows you to reason about how final the values are, so you can decide how much trust to put in the analysis you build on top. ## OpenAPI ````yaml /openapi.json get /market-access/v1alpha1/timeseries/aggregate-allocations openapi: 3.1.0 info: title: Engrate API version: 1.0.0 servers: - url: https://api.engrate.io security: - apiKeyAuth: [] paths: /market-access/v1alpha1/timeseries/aggregate-allocations: get: tags: - timeseries summary: List Aggregate Allocations description: >- List aggregate allocations timeseries data matching the provided filters. Note that this can return multiple values per ISP for the same dimensions, as the underlying storage is append-only. You tell those rows apart by looking at the [finality](/api-reference/allocations/models/finality) and known_at. If you are training a model this allows you to train the model on data that was known at the time the model will be running, avoiding training it on data that is "from the future". If you are doing controlling, this allows you to reason about how final the values are, so you can decide how much trust to put in the analysis you build on top. operationId: >- list_aggregate_allocations_market_access_v1alpha1_timeseries_aggregate_allocations_get parameters: - description: Inclusive lower bound on the settlement period start (RFC 3339). in: query name: isp_from required: true schema: description: Inclusive lower bound on the settlement period start (RFC 3339). format: date-time title: Isp From type: string - description: Exclusive upper bound on the settlement period start (RFC 3339). in: query name: isp_until required: true schema: description: Exclusive upper bound on the settlement period start (RFC 3339). format: date-time title: Isp Until type: string - description: >- Areas to read, each one as kind:code, where kind is one of metering_grid_area, control_area or scheduling_area, for example scheduling_area:10YDE-RWENET---I. Omit this parameter to read every area. in: query name: area required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: >- Areas to read, each one as kind:code, where kind is one of metering_grid_area, control_area or scheduling_area, for example scheduling_area:10YDE-RWENET---I. Omit this parameter to read every area. title: Area - description: Flow directions to read. Omit to read both. in: query name: flow_direction required: false schema: anyOf: - items: enum: - consumption - production type: string type: array - type: 'null' description: Flow directions to read. Omit to read both. title: Flow Direction - description: Balance groups to read. Omit to read every group. in: query name: balance_group required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: Balance groups to read. Omit to read every group. title: Balance Group - description: Suppliers to read. Omit to read every supplier. in: query name: supplier required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: Suppliers to read. Omit to read every supplier. title: Supplier - description: Aggregator roles to read. Omit to read every role. in: query name: aggregator required: false schema: anyOf: - items: $ref: '#/components/schemas/AggregatorRole' type: array - type: 'null' description: Aggregator roles to read. Omit to read every role. title: Aggregator - description: Allocation bases to read. Omit to read every basis. in: query name: allocation_basis required: false schema: anyOf: - items: $ref: '#/components/schemas/AllocationBasis' type: array - type: 'null' description: Allocation bases to read. Omit to read every basis. title: Allocation Basis - description: >- Market-specific dimensions to filter by, for markets where there are multiple separate aggregates that share the same common dimensions. Give each one as key:value, for example profile_scheme:sls. in: query name: market_dimension required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: >- Market-specific dimensions to filter by, for markets where there are multiple separate aggregates that share the same common dimensions. Give each one as key:value, for example profile_scheme:sls. title: Market Dimension responses: '200': content: application/json: schema: $ref: '#/components/schemas/AggregateAllocationsResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error components: schemas: AggregatorRole: description: >- ### Available aggregator roles - **grid_operator** — Indicates the source of the aggregation is a grid operator. - **transmission_operator** — Indicates the source of the aggregation is a transmission system operator. enum: - grid_operator - transmission_operator title: AggregatorRole type: string AllocationBasis: description: >- The basis tells you where the energy data for an aggregation is coming from: Is it directly metered values from smart meters, or is it something calculated from some standard profile? ### Available allocation basises - **metered** — Indicates this aggregation's data comes from directly metered energy, like from smart meters. - **profiled** — Indicates this aggregation's data is coming from a 'profile' of some kind, a pre-determined shape of consumption or production, usually coupled with some adjustment calculations, like adjusting for daily temperature or past annual metered consumption. enum: - metered - profiled title: AllocationBasis type: string AggregateAllocationsResponse: properties: values: items: $ref: '#/components/schemas/AggregateAllocationRecord' title: Values type: array required: - values title: AggregateAllocationsResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object AggregateAllocationRecord: description: >- A volume for one aggregate timeseries and one Imbalance Settlement Period (ISP). properties: external_id: title: External Id type: string finality: $ref: '#/components/schemas/Finality' examples: - final flow_direction: enum: - consumption - production title: Flow Direction type: string isp_resolution_minutes: title: Isp Resolution Minutes type: integer isp_time: format: date-time title: Isp Time type: string known_at: format: date-time title: Known At type: string quality: $ref: '#/components/schemas/AllocationQuality' examples: - calculated volume_wh: title: Volume Wh type: integer required: - external_id - finality - flow_direction - isp_resolution_minutes - isp_time - known_at - quality - volume_wh title: AggregateAllocationRecord type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object Finality: description: >- The settlement data comes in different levels of "finality". Each market has its own names for these levels, and all of them map to this common ladder. When one settlement period has more than one record, use the record with the highest finality, then the latest `known_at`. ### Available finalities - **preliminary** — The first level, sent before the market has all the data. - **revised** — The level used for corrections to the preliminary data. - **final** — The level used for settlement and invoicing. - **correction** — The level used for corrections when the final value was wrong. A correction replaces the final value. enum: - preliminary - revised - final - correction title: Finality type: string AllocationQuality: description: >- How the volume was arrived at, in ascending order of trust. When one settlement period carries several records, prefer the highest quality. ### Available allocation qualities - **provisional** — A placeholder the sender intends to replace. - **estimated** — Substituted because no reading was available: profiled, interpolated, or copied from a comparable period. Expect it to be superseded. - **calculated** — Derived by a defined computation rather than read - **measured** — Read off the meter. enum: - provisional - estimated - calculated - measured examples: - measured title: AllocationQuality type: string securitySchemes: apiKeyAuth: in: header name: Authorization type: apiKey ````