Sessions & Local Market API¶
Base paths:
/core/api/communities/{community_id}/sessions/core/api/communities/{community_id}/bilateral_energy_allocations
A session is one 15-minute Interval Settlement Period (ISP) of a community. Market clearing turns the offers of a session into transactions between members, and settlement then prices those transactions. This page covers reading and deleting sessions, the market results and metrics of a session or period, and the bilateral energy allocation coefficients produced by dynamic allocation communities. For the concepts behind them see Market & Sessions, Renewable Energy Communities and Settlement. Transactions and settlement outputs have their own pages: Transactions and Settlement.
Read-only market API
Sessions are created, cleared and settled by background market and settlement runs, not by
this API. The only write operation here is the deletion of sessions in a date range. See
When Sessions Reset for how sessions return to
OPEN automatically.
Time zone
All timestamps in responses are timezone-aware and expressed in the platform time zone
(Europe/Lisbon, offset +00:00 in winter and +01:00 in summer). Energy is in kWh and
prices are in EUR/kWh.
Endpoint summary¶
| Method | Path | Purpose |
|---|---|---|
| GET | /core/api/communities/{community_id}/sessions |
List all sessions of a community |
| GET | /core/api/communities/{community_id}/sessions/pagination |
List sessions with filters, sorting and pagination |
| GET | /core/api/communities/{community_id}/sessions/{session_id}/info |
Basic information of one session |
| GET | /core/api/communities/{community_id}/sessions/{session_id}/market |
Offers and transactions of one session |
| GET | /core/api/communities/{community_id}/sessions/{session_id}/settlement |
Settlement revenues of one session, per member and per resource |
| GET | /core/api/communities/{community_id}/sessions/metrics/all/market |
Aggregated market metrics for a date range |
| DELETE | /core/api/communities/{community_id}/sessions/between_dates |
Delete sessions in a date range |
| GET | /core/api/communities/{community_id}/bilateral_energy_allocations/pagination |
List bilateral energy allocations with filters and pagination |
| GET | /core/api/communities/{community_id}/bilateral_energy_allocations/data |
Allocation coefficients as JSON for a date range |
| GET | /core/api/communities/{community_id}/bilateral_energy_allocations/export |
Allocation coefficients as a ZIP of DSO CSV files |
All endpoints require a Bearer token (see Authentication).
In every route, community_id is checked against the caller's memberships before anything else
runs.
Session status values¶
status is one of the following values (SessionStatus in the code). In the current market
and settlement code a session moves from OPEN to WAITING_SETTLEMENT (or NO_TRANSACTIONS)
when market clearing finishes, and to SETTLED when settlement finishes. The
session lifecycle describes the same flow in
conceptual terms (CLEARED there).
| Status | Meaning |
|---|---|
OPEN |
Session is active; waiting for market clearing. Sessions return here when data they depend on changes |
WAITING_SETTLEMENT |
Market clearing produced transactions; waiting for settlement |
NO_TRANSACTIONS |
Market clearing ran but produced no transaction; still picked up by settlement |
SETTLED |
Settlement computed |
CLEARED |
Conceptual "cleared" state of the lifecycle; transactions recorded |
MISSING_DSO_INFO, DSO_COEFFICIENTS_ACCEPTED |
DSO data states of dynamic allocation communities; the market run picks these sessions up again together with OPEN and CLEAR_ERROR |
CLEAR_ERROR, SETTLEMENT_ERROR, LOADS_CONVERSION_ERROR, ERROR |
A processing stage failed (CLEAR_ERROR and SETTLEMENT_ERROR are retried by the next market or settlement run respectively) |
PUBLISHED, CLEARED_DYNAMIC_PHASE_1, WAITING_DSO_COEFFICIENTS, WAITING_DSO_INFO |
Defined in the enum for dynamic and DSO-driven flows |
ANY |
Internal filter value meaning "any status"; never stored on a session |
Sessions¶
List Sessions¶
Returns every session of the community, newest first (ordered by datetime_timestamp
descending). Use it for small communities or to build a session picker; for large histories use
the paginated endpoint.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
Example
curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"status": "SETTLED",
"community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"community_market_rate": "VANILLA_IMR",
"community_allocation_coefficient": "PROPORTIONAL",
"is_adjusted": false
}
]
Tip
There is no pagination: a community has up to 96 sessions per day, so a year is roughly
35,000 rows. community_market_rate and community_allocation_coefficient are the values
used when the session was cleared (see Market Rates and
Allocation Coefficient Methods), so they
may differ between sessions if the community configuration changed over time. is_adjusted
is a flag on the session (false by default). An unknown
community_id returns 404.
List Sessions (Paginated)¶
Returns one page of sessions together with transaction and offer counts, and the distinct dates, times and statuses available for building filter drop-downs. This is the endpoint behind the sessions table of the web interface.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
limit |
query | integer | Yes | Maximum number of sessions to return |
offset |
query | integer | Yes | Number of sessions to skip |
date |
query | string | No | Only sessions on this date, format YYYY-MM-DD |
time |
query | string | No | Only sessions starting at this time, format HH:MM:SS |
status |
query | string | No | Only sessions with exactly this status (see status values) |
sortColumn |
query | string | No | Column to sort by: date, time or any session column such as status |
sortDirection |
query | string | No | asc or desc. Any other value sorts descending |
Example
curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/pagination?limit=20&offset=0&date=2026-07-15&status=SETTLED&sortColumn=time&sortDirection=asc" \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
{
"total_count": 96,
"data": [
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"datetime_timestamp": "2026-07-15T00:00:00+01:00",
"status": "SETTLED",
"community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"community_market_rate": "VANILLA_IMR",
"community_allocation_coefficient": "PROPORTIONAL",
"is_adjusted": false,
"transaction_count": 12,
"offer_count": 18
}
],
"distinct_dates": [{"date": "2026-07-15"}],
"distinct_times": [{"time": "00:00:00"}, {"time": "00:15:00"}],
"distinct_status": [{"status": "SETTLED"}, {"status": "OPEN"}]
}
Tip
- Sorting is applied only when both
sortColumnandsortDirectionare sent; otherwise sessions are returned newest first. total_countis the number of sessions matching the filters, so it can be used to compute the number of pages.distinct_datesanddistinct_timescover all sessions of the community, not only the filtered ones, whereasdistinct_statuslists the statuses present in the community.date,timeandsortColumnare not validated by the schema: a malformed date or time, or asortColumnthat is not a session column, causes a server error rather than422.transaction_countandoffer_countare the number of transactions and offers of each returned session.
Get Session Info¶
Returns the basic fields of one session without its offers and transactions. Use it to check a
session's status cheaply, for example while waiting for a market run to finish.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
session_id |
path | UUID | Yes | Session identifier |
Example
curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/7c9e6679-7425-40de-944b-e07fc1f90ae7/info \
-H "Authorization: Bearer $TOKEN"
Response
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"status": "CLEARED",
"community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"community_market_rate": "VANILLA_IMR",
"community_allocation_coefficient": "PROPORTIONAL",
"is_adjusted": false
}
Tip
Returns 404 (Session with id: ... does not exist.) when the session does not exist. The
session is looked up by session_id alone; community_id in the path is used for the
permission check, so always pass the community the session belongs to.
Get Session Market Results¶
Returns one session together with all the offers submitted to the market and all the transactions it produced. Use it to inspect how a single interval cleared.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
session_id |
path | UUID | Yes | Session identifier |
exclude_deleted |
query | string | No | Accepted (true/false) but currently has no effect on the result |
Example
curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/7c9e6679-7425-40de-944b-e07fc1f90ae7/market \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
{
"status": "CLEARED",
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"community_market_rate": "VANILLA_IMR",
"community_allocation_coefficient": "PROPORTIONAL",
"is_adjusted": false,
"offers": [
{
"type": "l_sell",
"price": 0.09,
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"energy": 1.25,
"matched_energy": 1.25,
"meter_id": "9b2f3c1e-5d4a-4f0b-8c6e-1a2b3c4d5e6f",
"community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
],
"transactions": [
{
"id": "0e5c8a7d-2b61-4a3f-9d10-6f7a8b9c0d1e",
"price": 0.09,
"energy": 1.25,
"transaction_type": "LEM",
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider_meter_id": "9b2f3c1e-5d4a-4f0b-8c6e-1a2b3c4d5e6f",
"provider_user_id": "11111111-2222-4333-8444-555555555555",
"provider_resource_id": "66666666-7777-4888-8999-aaaaaaaaaaaa",
"receiver_meter_id": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
"receiver_user_id": "12121212-3434-4545-8656-787878787878",
"receiver_resource_id": null
}
]
}
Tip
- Offer
typeisl_sell(energy offered by a provider) orl_buy(energy requested by a receiver).matched_energyis the part of the offer that was cleared, in kWh. - A session that has not been cleared yet (
OPEN) returns emptyoffersandtransactionslists. See Transaction Types for the possibletransaction_typevalues. - Unknown
session_idreturns404. For transactions over a period rather than a single session use the Transactions API.
Get Session Settlement¶
Returns the settlement revenue fields of one session, keyed by member and, within each member, by resource. Use it for a quick per-session view of what each member and resource earned or paid. Full settlement outputs and file exports are described in Settlement.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
session_id |
path | UUID | Yes | Session identifier |
exclude_deleted |
query | string | No | Accepted (true/false) but currently has no effect on the result |
Example
curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/7c9e6679-7425-40de-944b-e07fc1f90ae7/settlement \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
{
"members": {
"12121212-3434-4545-8656-787878787878": {
"rev_total": -0.42,
"rev_total_no_csc": -0.55,
"rev_lem_trd": -0.11,
"rev_slc_soc": -0.01,
"rev_sup": -0.30,
"rev_sur": 0.0,
"rev_total_pow": -0.002,
"rev_total_pow_no_csc": -0.003,
"rev_pow": -0.002
}
},
"member_resources": {
"11111111-2222-4333-8444-555555555555": {
"66666666-7777-4888-8999-aaaaaaaaaaaa": {
"rev_total": 0.11,
"rev_lem_trd": 0.11,
"rev_sup": 0.0,
"rev_sur": 0.0,
"rev_total_pow": 0.0,
"rev_pow": 0.0
}
}
}
}
Tip
- Values are in EUR and signed: revenues positive, costs negative.
rev_total_no_cscis the hypothetical total without participating in the community. The meaning of eachrev_*field is documented in Settlement. membersis keyed by member (user) id;member_resourcesis keyed by member id and then resource id.- The session id is not checked for existence: an unknown or not yet settled session returns
two empty objects instead of
404.
Market metrics¶
Get Community Market Metrics¶
Aggregates the community's transactions between two dates into a single payload: overall average price and transacted energy, energy bought and sold per member and per member-resource, the average price per interval, and totals per provider and receiver pair.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
start_date |
query | date | Yes | First day to include, YYYY-MM-DD |
end_date |
query | date | Yes | Last day to include, YYYY-MM-DD (the whole day is included) |
granularity |
query | enum | No | Granularity of average_prices_list: MIN15 (default), HOUR, DAY, MONTH or YEAR |
Example
Response (abridged)
{
"transacted_energy": 1830.4,
"average_price": 0.087,
"average_prices_list": [
{"datetime_timestamp": "2026-07-01T00:00:00+01:00", "price": 0.083},
{"datetime_timestamp": "2026-07-02T00:00:00+01:00", "price": 0.091}
],
"member_market_metrics": [
{
"member_id": "12121212-3434-4545-8656-787878787878",
"member_name": "Maria Silva",
"energy_bought": 240.5,
"energy_sold": 0.0
}
],
"member_resource_market_metrics": [
{
"member_id": "11111111-2222-4333-8444-555555555555",
"member_name": "Joao Costa",
"resource_id": "66666666-7777-4888-8999-aaaaaaaaaaaa",
"resource_name": "Rooftop PV",
"energy_bought": 0.0,
"energy_sold": 310.2
}
],
"transactions_total": [
{
"provider_member_name": "Joao Costa",
"receiver_member_name": "Maria Silva",
"e_lem": 240.5,
"p_lem": 0.087,
"rev_lem": 20.92
}
]
}
Tip
transacted_energyis the sum of transaction energy in kWh.average_priceis the simple (unweighted) mean of the transaction prices in EUR/kWh, and is0when there are no transactions.p_lemintransactions_totalis, by contrast, energy-weighted (rev_lem / e_lem).average_prices_listaverages the transaction prices of each 15-minute interval and fills every missing interval between the first and last day that has transactions with price0. With a coarsergranularity, zero-priced intervals are ignored when averaging, so empty intervals do not drag the mean down.member_market_metricslists every user with theMEMBERrole in the community (even those without transactions, with zero energy).member_resource_market_metricshas one row per member-resource ownership.transactions_totalhas one row per provider and receiver meter/resource combination, which is the same grouping as the "Transactions Total" sheet of the billing guide (see Settlement file exports).- With no transactions in the range, the lists of members are still returned with zeros and
average_prices_listandtransactions_totalare empty. - An invalid
granularityor date returns422.
Deleting sessions¶
Delete Sessions Between Dates¶
Deletes all sessions of the community whose local date (Europe/Lisbon) falls between
start_date and end_date, both inclusive, and returns how many were removed. Use it to wipe a
period before regenerating it.
Destructive operation
Deleting a session also deletes the data attached to it through cascading foreign keys, such as its offers, transactions and bilateral energy allocations. This cannot be undone. Uploaded meter data is not part of a session and is not removed.
Auth / permissions: community admin or platform super-user. Community members receive 403
(Community members can only perform read operations).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
start_date |
query | date | Yes | First day to delete, YYYY-MM-DD |
end_date |
query | date | Yes | Last day to delete, YYYY-MM-DD (inclusive) |
Example
curl -X DELETE "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/between_dates?start_date=2026-07-01&end_date=2026-07-07" \
-H "Authorization: Bearer $TOKEN"
Response
Tip
- The range is evaluated on the Europe/Lisbon calendar day of each session, so
start_date=2026-07-01&end_date=2026-07-01removes exactly that local day (96 sessions on a normal day, 92 or 100 on the daylight-saving change days). - The dates are not checked against each other: an
end_datebeforestart_datesimply deletes nothing and returns{"deleted_count": 0}. - After deleting, the removed periods must be created and cleared again by the market run; see Market & Sessions.
Bilateral energy allocations¶
A bilateral energy allocation is the share of a provider CPE's production assigned to a
receiver CPE in one 15-minute interval. The allocation coefficient_value is produced by market
clearing in communities with dynamic allocation (DYNAMIC / TREE_DNAC, see
Allocation Coefficient Methods and
Market Rates) and is then submitted to the DSO for
validation. See the glossary and the
dynamic allocation coefficients export
for the end-to-end workflow. The endpoints below are read-only.
List Bilateral Energy Allocations (Paginated)¶
Returns one page of the stored allocation rows with filters on date, time and meter pair, and the distinct dates and times available. Use it to browse and audit the allocations that clearing produced.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
limit |
query | integer | Yes | Maximum number of rows to return |
offset |
query | integer | Yes | Number of rows to skip |
date |
query | string | No | Only rows on this date, format YYYY-MM-DD |
time |
query | string | No | Only rows at this time, format HH:MM:SS |
provider_meter_id |
query | UUID | No | Only rows where this meter is the provider |
receiver_meter_id |
query | UUID | No | Only rows where this meter is the receiver |
sort_column |
query | string | No | date, time or any column of the row (energy, coefficient_value, provider_meter_id, ...). Unknown names fall back to datetime_timestamp |
sort_direction |
query | string | No | asc; any other value sorts descending |
Example
curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/bilateral_energy_allocations/pagination?limit=50&offset=0&date=2026-07-15&sort_column=coefficient_value&sort_direction=desc" \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
{
"total_count": 1440,
"data": [
{
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"provider_meter_id": "9b2f3c1e-5d4a-4f0b-8c6e-1a2b3c4d5e6f",
"receiver_meter_id": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
"session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"energy": 0.62,
"coefficient_value": 0.4
}
],
"distinct_dates": [{"date": "2026-07-15"}],
"distinct_times": [{"time": "10:00:00"}, {"time": "10:15:00"}]
}
Tip
energyis in kWh;coefficient_valueis the allocation coefficient (a fraction between 0 and 1) and may benullwhen no coefficient was stored for the row.- Without
sort_columnrows are returned newest first.total_countreflects the active filters, whiledistinct_datesanddistinct_timesare computed with the same filters as the page. dateandtimeare not validated by the schema;limitandoffsetare required and a missing one returns422.
Get Bilateral Energy Allocations Data (JSON)¶
Returns the allocation coefficients for every ordered pair of the community's active CPE meters and every 15-minute interval of the date range, as JSON. It is meant for machine-to-machine integrations; to obtain the files that are submitted to the DSO use the ZIP export.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
start_date |
query | date | Yes | First day, YYYY-MM-DD (Europe/Lisbon day) |
end_date |
query | date | Yes | Last day, YYYY-MM-DD (inclusive) |
Example
curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/bilateral_energy_allocations/data?start_date=2026-07-15&end_date=2026-07-15" \
-H "Authorization: Bearer $TOKEN"
Response (abridged)
[
{
"datetime_timestamp": "2026-07-15T10:00:00+01:00",
"receiver_identifier": "PT0002000000000001AA",
"provider_identifier": "PT0002000000000002BB",
"coefficient_value": 0.45
}
]
Tip
- The result is a full grid: one row for every provider and receiver pair of different CPE
meters (
ACTIVEstatus only) in every interval of every day in the range, withcoefficient_value0when no coefficient was stored for that interval. A single day for a community with N CPEs therefore returnsN x (N - 1) x 96rows, so keep the range short. coefficient_valueis rounded to 3 decimals.receiver_identifierandprovider_identifierare the CPE identifiers of the meters (not UUIDs).- The set of CPE meters is the one effective today, not on the requested dates, and deleted meters are excluded.
- Missing
start_dateorend_datereturns422. - The
/dataformat is not aligned with the DSO's file layout. For DSO submissions use/export.
Export Bilateral Energy Allocations (ZIP)¶
Downloads a ZIP archive of semicolon-separated CSV files, one per provider and receiver CPE pair, in the layout expected by the DSO. Submit these files for validation of dynamic allocation coefficients.
Auth / permissions: any member of the community (admin or member), or a platform super-user.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
community_id |
path | UUID | Yes | Community identifier |
start_date |
query | date | Yes | First day, YYYY-MM-DD (Europe/Lisbon day) |
end_date |
query | date | Yes | Last day, YYYY-MM-DD (inclusive) |
Example
curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/bilateral_energy_allocations/export?start_date=2026-07-15&end_date=2026-07-15" \
-H "Authorization: Bearer $TOKEN" \
-o bilateral_energy_allocations_2026-07-15_2026-07-15.zip
Response
A binary stream with Content-Type: application/zip and
Content-Disposition: attachment; filename="bilateral_energy_allocations_<start_date>_<end_date>.zip".
Each CSV inside is named D_<community_identifier>_<receiver_cpe>_<provider_cpe>.csv and looks
like:
Data;Hora;CPE Consumo;CPE Produção;Coeficiente de partilha
20260715;0015;PT0002000000000001AA;PT0002000000000002BB;0.450
20260715;0030;PT0002000000000001AA;PT0002000000000002BB;0.000
Tip
- Only
ACTIVECPE meters are used. Consumers are CPEs of installation typeIAC,ICorIA; producers are CPEs of typeIAC,IPRorIA. For anIACproducer the file uses itsproduction_identifierinstead of itsidentifier, and producers without an identifier are skipped. A CPE is never paired with itself. - Each file has one row per 15-minute slot of every day in the range, with the coefficient to
3 decimals (
0.000when none is stored).Horais the slot end time inHHMMformat (0015for the first slot of the day,2400for the last), on the Europe/Lisbon clock: normal days have 96 slots, the spring-forward day 92 (0100-0145are skipped) and the fall-back day 100 (the extra slots continue as2415-2500). - The ZIP is generated inside the request (not as a background job), and it contains one file per provider and receiver pair for the whole range, so long ranges and communities with many CPEs make the request slow. For the asynchronous settlement exports see Settlement file exports.
- An unknown
community_idreturns404.