> ## Documentation Index > Fetch the complete documentation index at: https://docs.trlyr.com/llms.txt > Use this file to discover all available pages before exploring further. # Gets a selection of operational data of a block as a timeseries. > Gets a selection of operational data of a block as a timeseries. Returns a JSON representation of the selected operational data and its metadata at 15 minute granularity. The user selects the relevant categories of operational data through the query parameter `categories`, which is a comma separated list. E.g. `categories=powerCapacityChargeAvailable,powerCapacityDischargeRated` The following categories are available for blocks: `powerCapacityChargeRated`: The rated charge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityChargeAvailable`: The available charge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityDischargeRated`: The rated discharge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityDischargeAvailable`: The available discharge power capacity of the block in kW, e.g. `8000.0`. `boundaryPower`: The wholesale power that the asset reaches at the boundary between delivery periods in kW. For example, `4000.0 kW` at 12:15 implies that asset will be delivering exactly 4000 kW at exactly 12:15, which is the boundary between the [12:00, 12:15] and [12:15, 12:30] delivery periods. This will in general be different from the scheduled power values for a delivery period which are reflective of the average power delivered over each periods. For more information on relevant ramping constraints, see the layr user guide. `deliveryPeriodSetpoint`: The wholesale power the asset ramps to between the two adjacent boundary powers in kW, considering the ramping constraints. For example, `4500.0 kW` at 12:00 means the asset ramps to 4500 kW somewhere within the [12:00, 12:15] delivery period. The setpoint is in general different from the schedule value, as the schedule value describes the average power throughout a quarter. Each setpoint is documented against the timestamp of its quarter — i.e., a setpoint with value `4500.0 kW` and timestamp 12:15 corresponds to the [12:15, 12:30] delivery period. Note that the setpoint level is not necessarily achieved at that exact point in time, but normally somewhere within the quarter. For more information on relevant ramping constraints, see the layr user guide. `schedule`: The active scheduled power output/input of the block in kW, e.g. `5000.0`. `acceptedSchedule`: The accepted schedule power for the block in kW, e.g. `4800.0`. `adjustedSchedule`: The adjusted schedule power for the block in kW, e.g. `3800.0`. `undeliverableSchedule`: The portion of the virtual asset's scheduled wholesale power in kW that is considered "protected" during an ongoing unavailability. State of energy changes that result from this power will be accounted against the frozen-energy of the asset. Along with the selected operational data, a metadata object is returned which provides the unit for the selected datapoint. For detailed information about schedule adjustments including the reason for adjustments, use the [block adjustments endpoint](/blocks/{blockID}/operational/adjustments). Note that it is required to provide `start` and `end` params to specify the time interval for which to retrieve values. This range is greedy, in that it will match any timeseries point included in its range, including on the boundaries. e.g., setting a start of `2025-06-17T00:00:00Z` and an end of `2025-06-17T00:30:00Z` would return the points at 00:00:00, 00:15:00, and 00:30:00 which collectively cover a period from 00:00:00 to 00:45:00. An example response would be: ```json { "data": { "powerCapacityChargeAvailable": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 8000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 8000.0 } ] }, "powerCapacityDischargeRated": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 8000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 8000.0 } ] }, "schedule": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 5000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 5000.0 } ] } } } ``` ## OpenAPI ````yaml https://api.sandbox.trlyr.com/docs/doc.json get /organisations/{organisationID}/virtual-assets/{virtualAssetID}/blocks/{blockID}/operational openapi: 3.1.0 info: description: > This API allows clients to manage virtual-assets and blocks on the terralayr system. A virtual asset is a virtual battery, it has static parameters that dictate how much power it can import / export, how much energy it can store, and how efficiently it charges / discharges. It also has a state of charge which changes as the virtual asset exports and imports power. A block represents a slice of the power capacity of a virtual asset over time, and has a schedule which can be updated to control what the virtual-asset will do. Virtual assets should be kept balanced: you should manage the schedule such that the such that state of charge at the end of its lifetime is 50%. It is possible to submit schedules that do not end at 50%, but the response will include information about how much imbalance is left. ### Authorization All the underneath requests require a Bearer-type `Authorization` Header i.e. in the form : `Authorization: Bearer `. To retrieve a valid token you must log in to our system using a password-username authentication as follows: ``` POST https://api.sandbox.trlyr.com/auth/public/authenticate ``` with the following JSON body: ``` { "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" } ``` Your username and password are the ones you created after receiving an invitation to join your organisation. You should receive a JSON response body from which you can extract your token under `access_token`. If you have any questions, don't hesitate to contact our account manager at the following address: support@trlyr.com. title: terralayr API version: 1.11.3 servers: - description: Production API url: https://api.trlyr.com - description: Sandbox API url: https://api.sandbox.trlyr.com security: [] tags: - name: virtual-assets - name: afrr - name: fcr - name: ancillary - name: blocks externalDocs: description: '' url: '' paths: /organisations/{organisationID}/virtual-assets/{virtualAssetID}/blocks/{blockID}/operational: get: tags: - blocks summary: Gets a selection of operational data of a block as a timeseries. description: >- Gets a selection of operational data of a block as a timeseries. Returns a JSON representation of the selected operational data and its metadata at 15 minute granularity. The user selects the relevant categories of operational data through the query parameter `categories`, which is a comma separated list. E.g. `categories=powerCapacityChargeAvailable,powerCapacityDischargeRated` The following categories are available for blocks: `powerCapacityChargeRated`: The rated charge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityChargeAvailable`: The available charge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityDischargeRated`: The rated discharge power capacity of the block in kW, e.g. `8000.0`. `powerCapacityDischargeAvailable`: The available discharge power capacity of the block in kW, e.g. `8000.0`. `boundaryPower`: The wholesale power that the asset reaches at the boundary between delivery periods in kW. For example, `4000.0 kW` at 12:15 implies that asset will be delivering exactly 4000 kW at exactly 12:15, which is the boundary between the [12:00, 12:15] and [12:15, 12:30] delivery periods. This will in general be different from the scheduled power values for a delivery period which are reflective of the average power delivered over each periods. For more information on relevant ramping constraints, see the layr user guide. `deliveryPeriodSetpoint`: The wholesale power the asset ramps to between the two adjacent boundary powers in kW, considering the ramping constraints. For example, `4500.0 kW` at 12:00 means the asset ramps to 4500 kW somewhere within the [12:00, 12:15] delivery period. The setpoint is in general different from the schedule value, as the schedule value describes the average power throughout a quarter. Each setpoint is documented against the timestamp of its quarter — i.e., a setpoint with value `4500.0 kW` and timestamp 12:15 corresponds to the [12:15, 12:30] delivery period. Note that the setpoint level is not necessarily achieved at that exact point in time, but normally somewhere within the quarter. For more information on relevant ramping constraints, see the layr user guide. `schedule`: The active scheduled power output/input of the block in kW, e.g. `5000.0`. `acceptedSchedule`: The accepted schedule power for the block in kW, e.g. `4800.0`. `adjustedSchedule`: The adjusted schedule power for the block in kW, e.g. `3800.0`. `undeliverableSchedule`: The portion of the virtual asset's scheduled wholesale power in kW that is considered "protected" during an ongoing unavailability. State of energy changes that result from this power will be accounted against the frozen-energy of the asset. Along with the selected operational data, a metadata object is returned which provides the unit for the selected datapoint. For detailed information about schedule adjustments including the reason for adjustments, use the [block adjustments endpoint](/blocks/{blockID}/operational/adjustments). Note that it is required to provide `start` and `end` params to specify the time interval for which to retrieve values. This range is greedy, in that it will match any timeseries point included in its range, including on the boundaries. e.g., setting a start of `2025-06-17T00:00:00Z` and an end of `2025-06-17T00:30:00Z` would return the points at 00:00:00, 00:15:00, and 00:30:00 which collectively cover a period from 00:00:00 to 00:45:00. An example response would be: ```json { "data": { "powerCapacityChargeAvailable": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 8000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 8000.0 } ] }, "powerCapacityDischargeRated": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 8000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 8000.0 } ] }, "schedule": { "metaData": { "unit": "kW" }, "dataPoints": [ { "timestamp": "2025-07-11T22:00:00Z", "value": 5000.0 }, { "timestamp": "2025-07-11T22:15:00Z", "value": 5000.0 } ] } } } ``` parameters: - description: Access token in: header name: Authorization required: true schema: default: Bearer type: string - description: Organisation ID in: path name: organisationID required: true schema: type: string - description: Virtual Asset ID in: path name: virtualAssetID required: true schema: type: string - description: Block ID in: path name: blockID required: true schema: type: string - description: Selected Operational Data Categories in: query name: categories required: true schema: type: string - description: Query start time in: query name: start required: true schema: type: string - description: Query end time in: query name: end required: true schema: type: string - description: Data granularity (optional, minimum 4s) in: query name: granularity schema: type: string requestBody: content: application/json: schema: type: object responses: '200': content: application/json: schema: $ref: '#/components/schemas/OperationalData' description: OK '400': description: Bad Request '401': description: Unauthorized '500': description: Internal Server Error components: schemas: OperationalData: properties: data: additionalProperties: $ref: '#/components/schemas/CategoryData' type: object required: - data type: object CategoryData: properties: dataPoints: items: $ref: '#/components/schemas/DataPoint' type: array uniqueItems: false metaData: $ref: '#/components/schemas/MetaData' required: - dataPoints - metaData type: object DataPoint: properties: timestamp: example: '2020-01-01T00:00:00+00:00' type: string value: example: 100 type: number required: - timestamp - value type: object MetaData: properties: unit: $ref: '#/components/schemas/types.Unit' required: - unit type: object types.Unit: enum: - '' - PCT - KW - KWH - KW/S - AMP - V - C - HZ - WH - W - RATIO - EFC - EUR - GC02EQKWH example: kW type: string x-enum-varnames: - UnitNone - UnitPercent - UnitKilowatt - UnitKilowattHr - UnitKilowattPerSecond - UnitAmpere - UnitVolt - UnitCelsius - UnitHertz - UnitWattHour - UnitWatt - UnitRatio - UnitCycles - UnitEuro - UnitCarbonIntensity ````