Rebase Energy Read API

openapi: 3.2.0
info:
  title: Rebase Grid Read API
  version: '1'
  description: 'REST API for European power system data: production, consumption, prices, exchanges, capacities

    and balancing, collected from TSOs, exchanges and transparency platforms. Every value is stored

    as the provider published it, with the time it became known and every later version.


    The guides at grid.rebase.energy/docs/v1/ explain entities, timeseries names, providers and

    reading values; this document is the endpoint contract. Before scripting calls, read

    grid.rebase.energy/docs/v1/guides/efficient-calls/: one timeseries per values call, 240

    requests per minute per key, at most 100,000 points per values request, and the paging rules.


    No API key is needed: every endpoint but `/me` answers a request without one, at 10 requests

    per minute per IP address (grid.rebase.energy/docs/v1/guides/open-access/). A free key raises

    the limit to 240 per minute.'
servers:
- url: https://grid.rebase.energy/api/v1
security:
- apiKey: []
- {}
tags:
- name: Read
  description: The values of one timeseries from one provider, in the version selected by `as_of`.
paths:
  /entities/{entity}/timeseries/{name}/values:
    get:
      tags:
      - Read
      summary: Timeseries values
      description: 'One point per interval of the series, each with its `valid_time`, `value`, `knowledge_time`

        and `annotation`; a point an upstream message stated (an outage change-point) also carries

        that `message` (id, revision, reason, status). `as_of` selects the version:


        | `as_of` | Response | Returns |

        |---|---|---|

        | omitted | `points` | the latest version of every value |

        | an RFC 3339 instant | `points` | every value as known at that instant |

        | an ISO 8601 duration (`PT1H`, `P1D`) | `snapshots` | one snapshot per period, anchored on `start` or on `at` |

        | `rolling` | `snapshots` | one snapshot per native step of the series |


        A snapshot is the whole window as known at its instant. Snapshots at which nothing was known

        are omitted and they stop at now even when `end` is later; an `as_of` in the future is 400.

        Snapshot responses page with `next`, passed back as `cursor`. The Reading values guide shows each

        case with an example.'
      parameters:
      - $ref: '#/components/parameters/entity'
      - $ref: '#/components/parameters/name'
      - name: provider
        in: query
        required: true
        schema:
          type: string
        description: Required even when the quantity has one provider. Missing or unknown → 400 listing the providers, with a message naming the parameter to add (`add provider=entsoe`).
      - name: start
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: 'Inclusive valid-time bound: an ISO 8601 instant with a UTC offset, or a bare date (`2026-11-09`) meaning 00:00 UTC that day. The window [start, end] may hold at most 100000 points at the series'' resolution; for a series without a known resolution it may span at most 366 days. A larger window is 400 (`param: end`): narrow it.'
      - name: end
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: 'Inclusive valid-time bound, in the same forms as `start`. Same window cap as `start`: at most 100000 points at the series'' resolution, or 366 days without a known resolution; larger is 400. Bulk snapshots stop at now even when `end` is later; each snapshot still holds the rows forecast past now.'
      - name: as_of
        in: query
        required: false
        schema:
          type: string
        description: 'Omitted → flat, latest version of every value. An RFC 3339 instant → flat, every value as known at that instant.

          `rolling` → bulk, one snapshot per native step of the series. An ISO 8601 duration (PT1H, PT6H, P1D) → bulk, one snapshot per period anchored on `start`.

          A snapshot is the whole window as known at its instant. Snapshots at which nothing is known are omitted. An as_of in the future is 400.

          '
      - name: at
        in: query
        required: false
        schema:
          type: string
          pattern: ^\d{2}:\d{2}$
        description: Anchor for a period `as_of`, UTC wall-clock time.
      - name: max_snapshots
        in: query
        schema:
          type: integer
          default: 100
          maximum: 1000
        description: Bulk page size.
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque, from `next`.
      - name: columns
        in: query
        schema:
          type: string
        description: 'For a series with several columns (metadata `columns`), the subset to return, comma-separated: `p50,p90`. 400 on a plain series or an unknown column.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ValuesFlat'
                - $ref: '#/components/schemas/ValuesBulk'
              examples:
                latest:
                  value:
                    entity: SE-SE3
                    name: consumption.realised_load.total_load
                    provider: entsoe
                    unit: MW
                    resolution: PT15M
                    publication_time: measured
                    as_of: latest
                    points:
                    - valid_time: '2026-10-09T06:30:00Z'
                      value: 10100
                      knowledge_time: '2026-10-09T08:02:59Z'
                      annotation: null
                    - valid_time: '2026-10-09T06:45:00Z'
                      value: 10100
                      knowledge_time: '2026-10-09T08:02:59Z'
                      annotation: a03_forward_fill
                    - valid_time: '2026-10-09T07:00:00Z'
                      value: 10474
                      knowledge_time: '2026-10-09T08:02:59Z'
                      annotation: null
                bulk:
                  value:
                    entity: SE-SE3
                    name: consumption.realised_load.total_load
                    provider: entsoe
                    unit: MW
                    resolution: PT15M
                    publication_time: measured
                    as_of: PT6H
                    snapshots:
                    - as_of: '2026-10-01T06:00:00Z'
                      points:
                      - valid_time: '2026-10-01T00:00:00Z'
                        value: …
                        knowledge_time: …
                        annotation: null
                      - valid_time: …
                        value: … one point per quarter hour up to the last one known at 06:00, about 04:45 given the hour of latency
                    - as_of: '2026-10-01T12:00:00Z'
                      points:
                      - '… the window as known at 12:00: the same quarter hours as above, some with a newer version, plus the ones published since'
                    - as_of: …
                      points:
                      - … 28 snapshots in total, oldest first
                    next: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
      operationId: getEntitiesByEntityTimeseriesByNameValues
      x-operation-id-source: derived
  /timeseries/values:
    post:
      tags:
      - Read
      summary: Values of many timeseries
      description: 'The latest values of up to 2,000 timeseries over one shared window, in one call. The body

        lists the series; the response holds one block per series, in the same order, each exactly

        what the one-series values call returns for it. A series that cannot be read (unknown

        entity, name or provider, a window too large for it) answers an `error` block instead, and

        the rest are still read.


        A page holds whole series, up to 200,000 points in total and at least one series. When

        the next series would go over, the page stops and `next` is set: send it back as `cursor`

        with the same body. One call counts as one request against the rate limit.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManyValuesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManyValues'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
      operationId: postTimeseriesValues
      x-operation-id-source: derived
components:
  schemas:
    Point:
      type: object
      description: '`value` for a series with the one column `value`; `values` keyed by column for a series with several (see `columns`).'
      required:
      - valid_time
      - knowledge_time
      - annotation
      properties:
        valid_time:
          type: string
          format: date-time
        value:
          type:
          - number
          - 'null'
        values:
          type: object
          additionalProperties:
            type:
            - number
            - 'null'
        knowledge_time:
          type: string
          format: date-time
          description: For a series with several columns, the newest column's.
        annotation:
          type:
          - string
          - 'null'
          description: a03_forward_fill, a04_nowcast, a90_contract_warn, a99_retracted, or a combined code; never the provenance suffix. For a series with several columns, the code every column shares, else null.
        message:
          $ref: '#/components/schemas/Message'
    Message:
      type: object
      description: 'The upstream message that stated this point, present only on points that carry one: today the outage (REMIT unavailability) series, where every change-point names the notice behind it. A withdrawn or cancelled notice''s restore point carries that notice, so `status` says why the capacity came back. The key is omitted on every other point.'
      required:
      - id
      - revision
      - reason
      - status
      properties:
        id:
          type:
          - string
          - 'null'
          description: 'The message''s id: ENTSO-E''s document mRID, Elexon''s REMIT mrid.'
        revision:
          type:
          - string
          - 'null'
          description: The message's revision number, as published.
        reason:
          type:
          - string
          - 'null'
          description: 'The stated reason, at most 200 characters. ENTSO-E: each Reason as `code: text` (e.g. `B19`, `A95: Planned maintenance`), several joined by ` | `; Elexon: `cause | relatedInformation`.'
        status:
          type:
          - string
          - 'null'
          description: 'The message''s status as published. ENTSO-E: docStatus (`A09` cancelled, `A13` withdrawn; absent, so null, on an active document). Elexon: eventStatus (`Active`, `Inactive`, `Dismissed`).'
    ValuesBulk:
      allOf:
      - $ref: '#/components/schemas/ValuesHeader'
      - type: object
        required:
        - snapshots
        - next
        properties:
          snapshots:
            type: array
            description: Oldest first. A snapshot is the whole [start, end] window as known at its as_of. Empty snapshots are omitted.
            items:
              type: object
              required:
              - as_of
              - points
              properties:
                as_of:
                  type: string
                  format: date-time
                points:
                  type: array
                  items:
                    $ref: '#/components/schemas/Point'
          next:
            type:
            - string
            - 'null'
            description: Cursor for the next page; pass it as `cursor`. Null on the last page.
    ValuesHeader:
      type: object
      required:
      - entity
      - name
      - provider
      - unit
      - resolution
      - publication_time
      - as_of
      - columns
      properties:
        entity:
          type: string
        name:
          type: string
        provider:
          type: string
        unit:
          type: string
        resolution:
          type:
          - string
          - 'null'
        publication_time:
          type: string
          enum:
          - declared
          - measured
        licence:
          oneOf:
          - $ref: '#/components/schemas/Licence'
          - type: 'null'
          description: The publisher's licence and the credit line to show when republishing; null when the licence register has no entry.
        as_of:
          type: string
          description: '"latest", the instant echoed, "rolling", or the period echoed.'
        columns:
          type: array
          items:
            type: string
          minItems: 1
          description: 'The columns the points carry: `["value"]`, or the selection of `?columns=`.'
    Licence:
      type: object
      description: The terms the publisher releases the data under (src/gridapi/licences.yaml). The data stays under these terms; follow them and show `attribution` when you republish it.
      required:
      - name
      - url
      - attribution
      properties:
        name:
          type: string
          description: The licence, e.g. `CC BY 4.0`; `unreviewed` when its terms are still being read.
        url:
          type:
          - string
          - 'null'
          description: The publisher's terms page.
        attribution:
          type:
          - string
          - 'null'
          description: The credit line the publisher asks for.
    ManyValues:
      type: object
      required:
      - start
      - end
      - as_of
      - series
      - next
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        as_of:
          type: string
          enum:
          - latest
        series:
          type: array
          description: 'One block per series, in the order asked: its values, or its error.'
          items:
            oneOf:
            - $ref: '#/components/schemas/SeriesValues'
            - $ref: '#/components/schemas/SeriesError'
        next:
          type:
          - string
          - 'null'
          description: Cursor for the next page; send it as `cursor` with the same body. Null on the last page.
    SeriesValues:
      type: object
      description: 'One series'' latest values: the one-series values call''s answer, without `as_of` (it is on the page).'
      required:
      - entity
      - name
      - provider
      - unit
      - resolution
      - publication_time
      - columns
      - points
      properties:
        entity:
          type: string
        name:
          type: string
        provider:
          type: string
        unit:
          type: string
        resolution:
          type:
          - string
          - 'null'
        publication_time:
          type: string
          enum:
          - declared
          - measured
        licence:
          oneOf:
          - $ref: '#/components/schemas/Licence'
          - type: 'null'
          description: The publisher's licence and the credit line to show when republishing; null when the licence register has no entry.
        columns:
          type: array
          items:
            type: string
          minItems: 1
          description: '`["value"]`, or every column of a series with several.'
        points:
          type: array
          items:
            $ref: '#/components/schemas/Point'
    ValuesFlat:
      allOf:
      - $ref: '#/components/schemas/ValuesHeader'
      - type: object
        required:
        - points
        properties:
          points:
            type: array
            items:
              $ref: '#/components/schemas/Point'
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          enum:
          - not_found
          - bad_request
          - unauthorized
          - rate_limited
          - not_implemented
          - platform_unavailable
          - index_warming
        message:
          type: string
        param:
          type: string
          description: On bad_request, the offending parameter when there is one.
        anonymous:
          type: boolean
          description: On rate_limited, true when the request carried no API key.
        limit_rpm:
          type: integer
          description: On rate_limited without a key, the requests per minute an address may make.
        key_limit_rpm:
          type: integer
          description: On rate_limited without a key, the requests per minute a free key may make.
        retry_after_s:
          type: integer
          description: On rate_limited without a key, seconds to wait before repeating the request.
        sign_up:
          type: string
          description: Without a key, the form that requests a free one.
        docs:
          type: string
          description: Without a key, the documentation.
        info:
          type: string
          description: On rate_limited without a key, the Grid API product page.
        reason:
          type: string
          description: On not_found, `index_stale` when the series index may simply not have caught up with a new series.
        closest:
          type: array
          items:
            type: string
          description: On not_found, the three closest ids or names.
        providers:
          type: array
          items:
            type: string
          description: On bad_request for a missing/unknown provider, the providers available.
    SeriesError:
      type: object
      description: A series that could not be read, as asked, with the error the one-series values call answers for it.
      required:
      - entity
      - name
      - provider
      - error
      properties:
        entity:
          type: string
        name:
          type: string
        provider:
          type: string
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - not_found
              - bad_request
              - platform_unavailable
            message:
              type: string
    ManyValuesRequest:
      type: object
      required:
      - series
      - start
      - end
      properties:
        series:
          type: array
          minItems: 1
          maxItems: 2000
          description: The timeseries to read, each the three things one values call names. Read and answered in this order.
          items:
            type: object
            required:
            - entity
            - name
            - provider
            properties:
              entity:
                type: string
                description: An entity id, as in the one-series values call.
              name:
                type: string
                description: The quantity, `category.sub_category.definition[.component]`.
              provider:
                type: string
        start:
          type: string
          format: date-time
          description: Inclusive valid-time bound, shared by every series.
        end:
          type: string
          format: date-time
          description: Inclusive valid-time bound, shared by every series. A series whose window would hold more than 100000 points at its resolution (or span more than 366 days without one) answers an `error` block; the others are read.
        cursor:
          type: string
          description: The `next` of the previous page; send the rest of the body unchanged.
  responses:
    BadRequest:
      description: Missing or invalid parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Unknown entity, name or provider.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: The data platform did not answer (`platform_unavailable`) or the series index is still building (`index_warming`). Retry after the delay.
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: An API key that is not valid (`unauthorized`). A request with no key is served under the open limit; only `/me` answers it with this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'The per-minute request limit is spent (`rate_limited`): 240 for a key, 5 for an address without one. Retry after the delay.'
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    name:
      name: name
      in: path
      required: true
      description: The quantity, `category.sub_category.definition[.component]`, never with the provider suffix.
      schema:
        type: string
        pattern: ^[a-z0-9_]+(\.[a-z0-9_]+){2,}$
    entity:
      name: entity
      in: path
      required: true
      description: 'The entity id, e.g. `SE-SE3`, `Sweden`, `sync:NSA`, `ca:DE-Amprion`, `bnd:GB-B1`, `sub:Blyth`, `border:FI~SE-SE3`, `icx:BritNed`, or a plant, unit or portfolio: `plant:11WD4SAEK2HS---S`, `unit:…`, `portfolio:…` — the key, or the name after the kind prefix (`plant:Säckingen hydroelectric plant`). A name shared by several records is 404 listing their ids. See the Entities guide for every kind.'
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Optional. The Grid API key, also accepted as `?api_key=`; without it a request is answered at 10 per minute per IP address. How to get a key: grid.rebase.energy/docs/v1/guides/authentication/. The key is in the API tab of the grid map.'