generated: '2026-07-27'
method: searched
source: >-
  https://www.aeso.ca/assets/downloads/external/api/API-Access-Instructions-APIM-API-Gateway.pdf,
  https://developer-apim.aeso.ca/apis, openapi/*.json, live gateway probes 2026-07-27
summary: >-
  AESO's fourteen public APIs are one convention repeated fourteen times: a single GET operation (two
  in a couple of cases) that takes date-range or identifier query parameters and returns a JSON object
  whose only key is the human-readable report name, holding an array of flat value objects with
  string-typed fields. There is no envelope beyond that, no pagination, no expansion, no metadata
  block, no request-id header, no idempotency key and no rate-limit signalling. It is a report
  surface, not a resource API — and read as such it is remarkably consistent.
authentication:
  style: api-key
  primary:
    location: header
    name: API-KEY
  alternate:
    location: query
    name: subscription-key
  scheme_names: [apiKeyHeader, apiKeyQuery]
  anonymous_allowed: false
  anonymous_behaviour: >-
    HTTP 401 with the Azure APIM envelope {"statusCode": 401, "message": "Access denied due to missing
    subscription key. Make sure to include subscription key when making requests to an API."}
    (verified live 2026-07-27).
  key_issuance: self-serve, instant, no approval — https://developer-apim.aeso.ca/signup
  rotation: primary and secondary keys on the portal Profile page; regenerate there
  artifact: authentication/aeso-authentication.yml
idempotency:
  supported: false
  idempotency_key_header: null
  detail: >-
    AESO has no Idempotency-Key contract, and does not need one: all 16 documented operations are GET,
    which HTTP defines as safe and idempotent, and there is no write surface anywhere in the public
    API. Retrying any AESO call is inherently safe. No Idempotency pointer is wired in apis.yml because
    there is no idempotency-key mechanism to point at.
  http_method_safety: all operations are GET (safe + idempotent by method)
http:
  methods_supported: [GET]
  other_methods: >-
    Non-GET requests are not routed. A HEAD to a valid operation path returns 404 Resource Not Found
    from the gateway (probed 2026-07-27), and every OpenAPI declares a 405 "Invalid method" response.
  content_type: application/json
  transport: HTTPS (TLS 1.3 on apimgw.aeso.ca)
  base_url_pattern: https://apimgw.aeso.ca/public/{api}/{version}{path}
  secondary_host: https://gateway-apim.aeso.ca/public/{api}/{version}{path}
response_shape:
  style: named-report-envelope
  pattern: '{"<Report Name>": [ { ...flat value object... } ]}'
  examples:
  - '{"Pool Price Report": [{"begin_datetime_utc": "...", "begin_datetime_mpt": "...", "pool_price": "...", "forecast_pool_price": "...", "rolling_30day_avg": "..."}]}'
  typing_note: >-
    Numeric and timestamp fields are declared as JSON strings throughout, not numbers or date-time
    formats. Clients must parse prices, volumes and megawatt values from strings.
  timestamps:
    dual_zone: true
    fields: [begin_datetime_utc, begin_datetime_mpt]
    detail: >-
      Time-series reports carry both a UTC timestamp and a Mountain Prevailing Time timestamp on every
      row — a genuinely good convention for a market whose settlement hours are defined in local time.
      Daylight-saving transitions are announced separately in the Market Updates stream.
pagination:
  supported: false
  style: none
  detail: >-
    No page, offset, cursor or limit parameter appears in any operation. Result size is bounded by
    documented date-range caps instead — the Pool Price Report "will return data for a maximum of 1
    year at a time", and other range reports carry equivalent limits in their parameter descriptions.
    Clients paginate by walking the date range themselves.
filtering:
  style: query-parameters
  common_parameters:
  - name: startDate
    format: yyyy-MM-dd
    pattern: ^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$
    note: required on most range reports; earliest supported value is 2000-01-01 on Pool Price
  - name: endDate
    format: yyyy-MM-dd
    note: optional on most range reports; when omitted only startDate's data is returned
  - name: asset_ID
    note: filter to one or more market assets; values come from the Asset List API
  - name: pool_participant_ID
    note: filter to one participant; values come from the Pool Participant API
  current_value_endpoints:
  - /csd/summary/current
  - /csd/generation/assets/current
  - /price/systemMarginalPrice/current
  detail: >-
    Where a live value makes sense, AESO exposes a separate parameterless /current operation rather
    than a "latest" flag on the range operation.
field_expansion:
  supported: false
sparse_fields:
  supported: false
metadata:
  supported: false
  note: >-
    No customer-supplied metadata (this is a read-only public data surface). Some reports carry a
    server-side last_updated_datetime field; its labelling changed in the Current Supply Demand v2
    release (2025-07-30).
request_tracing:
  request_id_header: null
  detail: >-
    No X-Request-Id or correlation header is documented or returned. Gateway responses carry the Azure
    Request-Context header (appId), which is Application Insights plumbing rather than a client-facing
    trace id.
versioning:
  scheme: uri-path
  detail: version is a path segment — /v1, /v1.1, /v2 — and each version is a separate portal API entry
  artifact: lifecycle/aeso-lifecycle.yml
error_envelope:
  format: azure-apim
  fields: [statusCode, message]
  problem_json: false
  detail: >-
    Not RFC 9457. Every operation declares 400/401/403/404/405/500/503 with a plain English description
    and no response body schema, and the gateway returns the Azure APIM {statusCode, message} object.
  artifact: errors/aeso-problem-types.yml
rate_limiting:
  published: false
  headers_observed: []
  detail: >-
    No quota, no throttling policy and no X-RateLimit / RateLimit / Retry-After headers were observed on
    live gateway responses (probed 2026-07-27), and none is documented in the developer portal, the
    product record or the APIM API Gateway Instructions PDF. Treat limits as undefined and be
    conservative; the product allows one subscription per account.
caching:
  headers_observed: []
  detail: >-
    No Cache-Control, ETag or Last-Modified handling is documented. Report cadence is the practical
    cache key — settlement-hour data updates hourly, /current endpoints update continuously.
cors:
  documented: false
licensing:
  terms: https://www.aeso.ca/legal/
  summary: >-
    Non-commercial, personal or educational use only; material must not be modified and copyright
    notices must not be deleted. Any other use requires AESO's written permission. This is the single
    biggest constraint on the AESO API surface and it is legal, not technical.
cross_links:
  authentication: authentication/aeso-authentication.yml
  errors: errors/aeso-problem-types.yml
  lifecycle: lifecycle/aeso-lifecycle.yml
  changelog: changelog/aeso-changelog.yml
  data_model: data-model/aeso-data-model.yml
  sandbox: sandbox/aeso-sandbox.yml
  plans: plans/aeso-plans.yml