> ## 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 Imbalances > List the imbalance volumes that agree with the filters. Each imbalance series holds the imbalance of one balance group in one scheduling area, or one adjustment that the market included in it. On a total, a positive volume means that the balance group was long. On an adjustment, a positive volume makes the balance group longer. This can return more than one record per ISP for one imbalance series. Use the record with the highest `finality`, then the latest `stated_at`. When records have the same values in both fields, use the first of them in the response. The total includes its adjustments, and the net adjustment includes the adjustment classes. Do not add volumes across these levels. The API gives the status code 422 in these conditions: - `isp_from` or `isp_until` is missing, or it has no time zone offset. - A `market_dimension` filter is not in the format `key:value`. - A `market_dimension` filter has one key two times. - A `component_kind` or `component_value` filter has an unknown value. - An `external_id`, `scheduling_area`, `balance_group` or `market_dimension` filter exceeds its maximum number of values. ## OpenAPI ````yaml /openapi.json get /market-access/v1alpha1/timeseries/imbalance 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/imbalance: get: tags: - timeseries summary: List Imbalances description: >- List the imbalance volumes that agree with the filters. Each imbalance series holds the imbalance of one balance group in one scheduling area, or one adjustment that the market included in it. On a total, a positive volume means that the balance group was long. On an adjustment, a positive volume makes the balance group longer. This can return more than one record per ISP for one imbalance series. Use the record with the highest `finality`, then the latest `stated_at`. When records have the same values in both fields, use the first of them in the response. The total includes its adjustments, and the net adjustment includes the adjustment classes. Do not add volumes across these levels. The API gives the status code 422 in these conditions: - `isp_from` or `isp_until` is missing, or it has no time zone offset. - A `market_dimension` filter is not in the format `key:value`. - A `market_dimension` filter has one key two times. - A `component_kind` or `component_value` filter has an unknown value. - An `external_id`, `scheduling_area`, `balance_group` or `market_dimension` filter exceeds its maximum number of values. operationId: list_imbalances_market_access_v1alpha1_timeseries_imbalance_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: External ids of the imbalance series to read. in: query name: external_id required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: External ids of the imbalance series to read. title: External Id - description: >- EIC codes of the scheduling areas to read, for example `10YDE-EON------1`. Omit to read every area. in: query name: scheduling_area required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: >- EIC codes of the scheduling areas to read, for example `10YDE-EON------1`. Omit to read every area. title: Scheduling Area - 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: Component kinds to read. Omit to read both. in: query name: component_kind required: false schema: anyOf: - items: $ref: '#/components/schemas/ImbalanceComponentKind' type: array - type: 'null' description: Component kinds to read. Omit to read both. title: Component Kind - description: Component values to read. Omit to read every value. in: query name: component_value required: false schema: anyOf: - items: $ref: '#/components/schemas/ImbalanceComponentValue' type: array - type: 'null' description: Component values to read. Omit to read every value. title: Component Value - description: >- Market dimensions to filter by, as key:value. A market dimension is the market's own key and code for an imbalance series, for example the code of an adjustment class. A series matches when it has every pair. in: query name: market_dimension required: false schema: anyOf: - items: type: string maxItems: 500 type: array - type: 'null' description: >- Market dimensions to filter by, as key:value. A market dimension is the market's own key and code for an imbalance series, for example the code of an adjustment class. A series matches when it has every pair. title: Market Dimension responses: '200': content: application/json: schema: $ref: '#/components/schemas/ImbalancesResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error components: schemas: ImbalanceComponentKind: description: >- The level of an imbalance series. The total contains the adjustments, thus do not add a total and its adjustments together. ### Available imbalance component kinds - **total** — The imbalance of the balance group, with all adjustments included. - **adjustment** — An adjustment that the market included in the imbalance, with the sign it has in the imbalance. enum: - total - adjustment examples: - total title: ImbalanceComponentKind type: string ImbalanceComponentValue: description: >- The adjustment class of an imbalance series and its suffix: `_up` or `_down` for the regulation direction, `_net` for one signed series. `ALL` contains the classes, and each `_net` contains its `_up` and `_down`, thus never add across these levels. ### Available imbalance component values - **ALL** — On a total, the imbalance. On an adjustment, the net of all the adjustments that the market sends. - **afrr_up** — Automatic frequency restoration reserve (aFRR), upward regulation. - **afrr_down** — aFRR, downward regulation. - **afrr_net** — aFRR, both directions in one signed series. - **mfrr_up** — Manual frequency restoration reserve (mFRR), upward regulation. - **mfrr_down** — mFRR, downward regulation. - **mfrr_net** — mFRR, both directions in one signed series. - **redispatch_up** — Redispatch, upward regulation. - **redispatch_down** — Redispatch, downward regulation. - **redispatch_net** — Redispatch, both directions in one signed series. - **other_up** — A different adjustment class, upward. The market's own code for the class is in the market dimensions. - **other_down** — A different adjustment class, downward. The market's own code for the class is in the market dimensions. - **other_net** — A different adjustment class, both directions in one signed series. The market's own code for the class is in the market dimensions. enum: - ALL - afrr_up - afrr_down - afrr_net - mfrr_up - mfrr_down - mfrr_net - redispatch_up - redispatch_down - redispatch_net - other_up - other_down - other_net examples: - ALL title: ImbalanceComponentValue type: string ImbalancesResponse: properties: values: items: $ref: '#/components/schemas/ImbalanceRecord' title: Values type: array required: - values title: ImbalancesResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ImbalanceRecord: description: >- An imbalance volume for one imbalance series and one Imbalance Settlement Period (ISP). properties: external_id: description: >- The identifier of the imbalance series. The market gives it, or Engrate gives it in markets that do not give a stable identifier. title: External Id type: string finality: $ref: '#/components/schemas/ImbalanceFinality' examples: - final isp_resolution_minutes: description: >- The length of the ISP in minutes. This is usually 15, 30 or 60, depending on the market. title: Isp Resolution Minutes type: integer isp_time: description: >- The start of the Imbalance Settlement Period (ISP), as an ISO 8601 timestamp in UTC, for example `2026-01-01T00:00:00Z`. examples: - '2026-09-26T22:00:00Z' format: date-time title: Isp Time type: string known_at: description: >- When Engrate ingested the record, as an ISO 8601 timestamp in UTC. Use it to prevent look-ahead bias when you fit models: leave out the records that Engrate ingested after the time your model runs. format: date-time title: Known At type: string stated_at: description: >- The market's own timestamp for the settlement run of the record, as an ISO 8601 timestamp in UTC. format: date-time title: Stated At type: string volume_wh: description: >- The signed volume in Wh. On a total, a positive volume means that the balance group was long: it injected more, or withdrew less, than its trade schedule. On an adjustment, the sign is its effect on the imbalance: positive makes the balance group longer. examples: - -1250000 title: Volume Wh type: integer required: - external_id - finality - isp_resolution_minutes - isp_time - known_at - stated_at - volume_wh title: ImbalanceRecord 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 ImbalanceFinality: description: >- The settlement run of an imbalance. Each market has its own names for its runs, 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 `stated_at`. When records have the same values in both fields, use the first of them in the response. ### Available imbalance finalities - **preliminary** — The first run, before the market has all the data. - **revised** — A run that corrects the preliminary data. - **final** — The run used for settlement and invoicing. - **correction** — A run that corrects a wrong final value. A correction replaces the final value. enum: - preliminary - revised - final - correction examples: - preliminary title: ImbalanceFinality type: string securitySchemes: apiKeyAuth: in: header name: Authorization type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.