Skip to content

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

GET /core/api/communities/{community_id}/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)

GET /core/api/communities/{community_id}/sessions/pagination

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 sortColumn and sortDirection are sent; otherwise sessions are returned newest first.
  • total_count is the number of sessions matching the filters, so it can be used to compute the number of pages. distinct_dates and distinct_times cover all sessions of the community, not only the filtered ones, whereas distinct_status lists the statuses present in the community.
  • date, time and sortColumn are not validated by the schema: a malformed date or time, or a sortColumn that is not a session column, causes a server error rather than 422.
  • transaction_count and offer_count are the number of transactions and offers of each returned session.

Get Session Info

GET /core/api/communities/{community_id}/sessions/{session_id}/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

GET /core/api/communities/{community_id}/sessions/{session_id}/market

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 type is l_sell (energy offered by a provider) or l_buy (energy requested by a receiver). matched_energy is the part of the offer that was cleared, in kWh.
  • A session that has not been cleared yet (OPEN) returns empty offers and transactions lists. See Transaction Types for the possible transaction_type values.
  • Unknown session_id returns 404. For transactions over a period rather than a single session use the Transactions API.

Get Session Settlement

GET /core/api/communities/{community_id}/sessions/{session_id}/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_csc is the hypothetical total without participating in the community. The meaning of each rev_* field is documented in Settlement.
  • members is keyed by member (user) id; member_resources is 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

GET /core/api/communities/{community_id}/sessions/metrics/all/market

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

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/metrics/all/market?start_date=2026-07-01&end_date=2026-07-31&granularity=DAY" \
  -H "Authorization: Bearer $TOKEN"

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_energy is the sum of transaction energy in kWh. average_price is the simple (unweighted) mean of the transaction prices in EUR/kWh, and is 0 when there are no transactions. p_lem in transactions_total is, by contrast, energy-weighted (rev_lem / e_lem).
  • average_prices_list averages the transaction prices of each 15-minute interval and fills every missing interval between the first and last day that has transactions with price 0. With a coarser granularity, zero-priced intervals are ignored when averaging, so empty intervals do not drag the mean down.
  • member_market_metrics lists every user with the MEMBER role in the community (even those without transactions, with zero energy). member_resource_market_metrics has one row per member-resource ownership. transactions_total has 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_list and transactions_total are empty.
  • An invalid granularity or date returns 422.

Deleting sessions

Delete Sessions Between Dates

DELETE /core/api/communities/{community_id}/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

{ "deleted_count": 672 }

Tip

  • The range is evaluated on the Europe/Lisbon calendar day of each session, so start_date=2026-07-01&end_date=2026-07-01 removes 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_date before start_date simply 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)

GET /core/api/communities/{community_id}/bilateral_energy_allocations/pagination

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

  • energy is in kWh; coefficient_value is the allocation coefficient (a fraction between 0 and 1) and may be null when no coefficient was stored for the row.
  • Without sort_column rows are returned newest first. total_count reflects the active filters, while distinct_dates and distinct_times are computed with the same filters as the page.
  • date and time are not validated by the schema; limit and offset are required and a missing one returns 422.

Get Bilateral Energy Allocations Data (JSON)

GET /core/api/communities/{community_id}/bilateral_energy_allocations/data

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 (ACTIVE status only) in every interval of every day in the range, with coefficient_value 0 when no coefficient was stored for that interval. A single day for a community with N CPEs therefore returns N x (N - 1) x 96 rows, so keep the range short.
  • coefficient_value is rounded to 3 decimals. receiver_identifier and provider_identifier are 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_date or end_date returns 422.
  • The /data format is not aligned with the DSO's file layout. For DSO submissions use /export.

Export Bilateral Energy Allocations (ZIP)

GET /core/api/communities/{community_id}/bilateral_energy_allocations/export

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 ACTIVE CPE meters are used. Consumers are CPEs of installation type IAC, IC or IA; producers are CPEs of type IAC, IPR or IA. For an IAC producer the file uses its production_identifier instead of its identifier, 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.000 when none is stored). Hora is the slot end time in HHMM format (0015 for the first slot of the day, 2400 for the last), on the Europe/Lisbon clock: normal days have 96 slots, the spring-forward day 92 (0100-0145 are skipped) and the fall-back day 100 (the extra slots continue as 2415-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_id returns 404.