API Reference
Forward-looking 48h demand and carbon intensity, plus the IEX DAM implied price curve. Access is enforced per endpoint, not per page — check the table below before you integrate.
Access differs per endpoint
There is no single tier gate on this page. Each route below enforces its own entitlement, and every route is additionally capped by your plan's forecast_days window (echoed on every response as meta.data_window.forecast_days). Plans are listed on Pricing.
| Endpoint | Plans that can call it | Response below plan |
|---|---|---|
/forecast/demand | Student, Institutional, Growth, Enterprise | 402 feature_not_in_plan |
/forecast/carbon-intensity | Any API key (national). ?state= adds the state-level gate: Student, Institutional, Growth, Enterprise | 402 feature_not_in_plan on ?state= only |
/forecast/iex-forward-curve | Any API key. Lookback depth is what the plan changes, not access | No gate — the window is clamped instead |
/forecast/iex/dam/latest | Starter, Growth (latest DAM curve), Enterprise (full product) | 403 upgrade_required |
/forecast/iex/outlook/latest · /outlook/blocks | Growth, Enterprise (D+1 to D+30) | 403 upgrade_required, required_plan: growth |
/forecast/iex/{dam,gdam,rtm}/{blocks,hourly} | Growth, Enterprise | 403 upgrade_required, required_plan: growth |
/forecasts/dam · /forecasts/rtm · /forecasts/outlook | Student, Pro (24 hourly rows); Starter (96 blocks); Growth, Enterprise (96 blocks, plus as_of) | 402 entitlement_limit_reached |
/forecasts/vintages | Growth, Enterprise | 402 entitlement_limit_reached |
The demand-forecast gate is the allow_state_level policy flag, so it does not follow the price ladder: the Pro and Starter plans do not carry it, while the free Student and Institutional plans do. The canonical plan names are Sandbox, Student, Institutional, Grid AI, Pro, Starter, Growth, and Enterprise. Older four-tier labels — including "Trial" — are retired; a legacy paid key resolves to Growth.
/developer/v1/forecast/demandStudent · Institutional · Growth · EnterpriseNext-48h hourly demand forecast. National by default; pass ?state=<key> for a per-state forecast. Returns the demand_mw point (= p50) with the p10/p50/p90 uncertainty band and a per-IST-day peak head. Honest provenance: source is 'model' only when the trained 48h model is promoted to serving, and served is strictly source == 'model' (otherwise a seasonal-naive / climatology baseline is served with served=false).
statestringmaharashtra / MH / Maharashtra). Omit for the national all-India forecast.horizonintegerdefault: 48{
"data": {
"scope": "national",
"state": "All India",
"issued_at": "2026-07-04T06:00:00+00:00",
"as_of": "2026-07-04T06:00:00+00:00",
"horizon_hours": 48,
"source": "model",
"served": true,
"model_version": "national-48h-v3",
"coverage": { "band": "p10-p90", "notes": "national-48h-v3; anchor=recent-median" },
"peaks": [
{ "date_ist": "2026-07-04", "peak_mw": 238412.0, "peak_hour_ist": 15 }
],
"hours": [
{ "target_hour_ist": "2026-07-04T12:00:00", "hour_ist": 12,
"demand_mw": 236010.0, "p10_mw": 219100.0, "p50_mw": 236010.0, "p90_mw": 252920.0 }
]
},
"meta": { "scope": "national", "source": "model", "served": true }
}demand_mw equals p50_mw exactly — the same number every Atlas surface (the forecast page, /states, and the daily email) reads for the same issue. The old /forecast/national and /forecast/state/{state_key} paths are aliases of this endpoint (identical response, retained for back-compat), and /forecast/ledger — the predicted-vs-actual accuracy history — sits behind the same gate.
This gate is not the price ladder
The entitlement checked here is allow_state_level. Sandbox, Grid AI, Pro, and Starter keys receive 402 feature_not_in_plan on this route and on its two aliases, even though Starter is a paid plan. Student, Institutional, Growth, and Enterprise keys are allowed.
Supersedes the legacy 24h state forecast
This 48h forecast replaces the legacy 24h /api/intelligence/state-demand-forecast (now beta). New integrations should use /forecast/demand?state=<key>, which adds the p10/p50/p90 band and honest source/served provenance.
/developer/v1/forecast/carbon-intensityAny API keyHour-by-hour carbon intensity forecast. Each hour is the trailing hour-of-day average intensity for the scope, anchored to the latest observed value with a 6h fade so the series joins the actuals without a step. Any API key may call the national scope.
hoursintegerdefault: 24meta.requested_hours against meta.returned_hours to detect a clamp.statestring402 feature_not_in_plan when this is set.orderenumdefault: descdesc (nearest-term hour first) or asc.{
"data": {
"items": [
{ "timestamp": "2026-07-04T15:00:00+05:30", "state": "All India", "state_slug": "all-india",
"carbon_intensity_gco2_kwh": 688.4, "intensity_class": "high",
"total_generation_mw": 198420.5, "is_forecast": true }
],
"count": 24,
"forecast_hours": 24,
"state_slug": null,
"unit": "gCO2/kWh"
},
"meta": { "state": null, "requested_hours": 24, "returned_hours": 24, "order": "desc" }
}Timestamps are IST (+05:30). The plan window bites here rather than the entitlement: Sandbox, Grid AI, Pro, and Starter clamp at 7 days (168 h), Student and Institutional at 14 days (336 h), and Growth and Enterprise are uncapped.
/developer/v1/forecast/iex-forward-curveAny API keyImplied DAM price curve in monthly buckets, computed from settled IEX day-ahead history — not a forward-looking model output. Each month returns the average, median, P25/P75, min, max and standard deviation of market clearing price, plus an off-peak / solar / evening / night time-of-day profile.
Historical implied curve, not a price forecast
This endpoint aggregates settled DAM clearing prices over a trailing window. It carries no weather or holiday conditioning, no forward horizon, and no prediction interval. For a genuine block-level price forecast, use /forecast/iex/dam/latest below.
monthsintegerdefault: 12meta.returned_months for what you actually got.{
"data": {
"monthly_series": [
{ "month": "2026-06", "block_count": 2880,
"avg_mcp": 4218.36, "median_mcp": 3990.0,
"p25_mcp": 3180.5, "p75_mcp": 5010.25,
"min_mcp": 1500.0, "max_mcp": 10000.0, "stddev_mcp": 1487.92 }
],
"tod_profiles": {
"2026-06": {
"off_peak": { "block_count": 720, "avg_mcp": 3410.18, "median_mcp": 3290.0 },
"solar": { "block_count": 1440, "avg_mcp": 3688.42, "median_mcp": 3520.0 },
"evening": { "block_count": 480, "avg_mcp": 6120.77, "median_mcp": 5980.0 },
"night": { "block_count": 240, "avg_mcp": 4402.11, "median_mcp": 4310.0 }
}
},
"overall_avg_mcp": 4218.36,
"months_available": 1,
"lookback_months": 1
},
"meta": { "requested_months": 12, "returned_months": 1 }
}Prices are INR/MWh. Months are IST calendar months (YYYY-MM) returned in ascending order — the axis is semantic, so this route is exempt from the order parameter. Time-of-day buckets are IST: off-peak 00:00–06:00, solar 06:00–18:00, evening 18:00–22:00, night 22:00–24:00.
/developer/v1/forecast/iex/dam/latestStarter · Growth · EnterpriseMost-recently published day-ahead 96-block price forecast: p10/p50/p90 plus a price-cap-hit spike probability per 15-minute block, with issuing timestamp, model version and staleness in minutes. This is the block-level product the forward curve is often mistaken for.
DAM forecasts publish once daily at 00:30 UTC (06:00 IST), ahead of the exchange's 11:00 IST bid gate. Starter and Growth keys read this curve with meta.access: "dam_slice" rather than "full". Growth keys also read the D+1 to D+30 outlook and the DAM, G-DAM and RTM delivery-day curves documented below. Every other plan receives 403 upgrade_required.
The rest of the IEX Market Forecasts suite is Enterprise
Beyond the outlook and the delivery-day curves, the /developer/v1/forecast/iex/* family — RTM next-six-block forecasts and vintages, the G-DAM shadow outlook, vs-actual reconciliation, decision metrics, benchmark comparisons, and bounded replay of the 30-day history window — is gated to Enterprise and returns 403 upgrade_required otherwise. See the IEX Market Forecasts product page — it also carries the open accuracy tracker — and Pricing for plans.
/developer/v1/forecast/iex/outlook/latestGrowth · EnterpriseThe rolling 30-day day-ahead-market outlook — one row per IST delivery day, D+1 to D+30, issued once a day after the DAM auction clears (about 06:10 IST). Each row carries both day-average bases: the volume-weighted price (VWAP p10/p50/p90 and mean — what the market actually paid per MWh, the headline) and the unweighted 96-block mean (p05..p95), plus the four time-of-day medians, the probability that the 18–22h evening clears at the ₹10,000/MWh ceiling and the expected number of capped blocks. Every number comes from one joint simulation per delivery day, so blocks, time-of-day averages, cap risk and the day average agree with each other.
Two day-average prices, on purpose
The VWAP and the unweighted mean diverge violently once blocks pin at the ceiling (13 Sep 2026: ₹7,974 unweighted against ₹5,119 VWAP). Read vwap_q50 unless you buy a flat MW block across every period of the day. Starter's desk slice covers the D+1 curve only; this product is in Growth and Enterprise.
{
"data": [
{ "target_date": "2026-09-16", "horizon_days": 1,
"vwap_q10": 4269.0, "vwap_q50": 5555.0, "vwap_q90": 5853.0, "vwap_mean": 5290.0,
"level_q05": 5310.0, "level_q10": 5920.0, "level_q25": 6870.0, "level_q50": 7733.0,
"level_q75": 8410.0, "level_q90": 9010.0, "level_q95": 9340.0, "level_mean": 7690.0,
"tod_off_peak_q50": 4210.0, "tod_solar_q50": 2980.0, "tod_evening_q50": 10000.0, "tod_night_q50": 6120.0,
"tod_evening_q90": 10000.0, "tod_evening_pcap": 0.99,
"n_cap_mean": 61.4, "n_cap_q10": 44.0, "n_cap_q90": 71.0,
"day_max_q50": 10000.0, "day_max_q90": 10000.0, "cap_rs_mwh": 10000.0,
"model_version": "dam-30d-v2.2", "issued_at": "2026-09-15T00:40:00+00:00" }
],
"meta": { "market": "DAM", "product": "outlook_14d", "as_of": "2026-09-15", "delivery_days": 30,
"issued_at": "2026-09-15T00:40:00+00:00", "model_version": "dam-30d-v2.2",
"freshness": { "issued_at": "2026-09-15T00:40:00+00:00", "staleness_minutes": 412 } }
}meta.as_of is the last cleared delivery day the issue was built from; horizon_days counts from it. meta.product reads outlook_14d, the name existing integrations match on, although an issue now covers 30 delivery days. Measured out of sample over 390 delivery days (Sep 2025 – Sep 2026): VWAP median error 9.7% at D+1 and about 16% from D+7 to D+30; the 80% bands cover 80% of outcomes at D+1 and 74–75% beyond D+14. Block-level skill is largest at one to three days ahead, and the cap probability is a lower bound while the market tightens. Past about D+20 the forecast is mostly the 90-day level plus seasonality, so read D+15 to D+30 as a weekly and regime outlook (level, capped-block count), not as block-by-block prices.
/developer/v1/forecast/iex/outlook/blocksGrowth · EnterpriseThe 96 fifteen-minute blocks of one delivery day inside the latest 30-day outlook: p05..p95, the mean and the probability that the block clears at the ceiling. 404 no_forecast when the requested day is not in the latest issue.
datestringYYYY-MM-DD, between D+1 and D+30 of the latest issue.{
"data": [
{ "target_ts": "2026-09-21T18:30:00+00:00", "block": 0, "horizon_days": 7,
"q05": 2420.0, "q10": 2860.0, "q25": 3520.0, "q50": 4400.0, "q75": 5060.0, "q90": 5940.0, "q95": 6600.0,
"mean_rs_mwh": 4532.0, "p_cap": 0.04, "model_version": "mh-v2" }
],
"meta": { "market": "DAM", "product": "outlook_14d", "target_date": "2026-09-22", "horizon_days": 7,
"issued_at": "2026-09-15T00:40:00+00:00", "model_version": "mh-v2",
"freshness": { "issued_at": "2026-09-15T00:40:00+00:00", "staleness_minutes": 412 } }
}Block 0 starts at 00:00 IST; target_ts is the block start in UTC. Blocks of one simulated day are tied together by the rank pattern of a real historical day, so the evening peak caps together or not at all — read p_cap with the day's n_cap_mean from /outlook/latest.
/developer/v1/forecast/iex/{dam,gdam,rtm}/blocksGrowth · EnterpriseThe 96 fifteen-minute blocks of one IST delivery day for one IEX market: percentiles q05 to q95 in Rs/MWh. DAM covers any of the next 30 delivery days and adds the block's expected price (mean_rs_mwh) and the probability that it clears at the price cap (p_cap); G-DAM and RTM cover the next delivery day.
datestringYYYY-MM-DD. Required.issuestringYYYY-MM-DD = the newest issue published on that IST day; YYYY-MM-DDTHH:MM = the newest issue published at or before that IST time (an offset such as Z is accepted, so a previous response's meta.issued_at returns that issue again). Default: the newest issue covering the date.{
"data": [
{ "target_ts": "2026-10-20T12:30:00Z", "block": 73,
"q05": 2030.6, "q10": 2361.8, "q25": 2876.7, "q50": 4537.1,
"q75": 10000.0, "q90": 10000.0, "q95": 10000.0,
"mean_rs_mwh": 6299.9, "p_cap": 0.469 }
],
"meta": { "market": "DAM", "product": "dam_forecast_30d", "target_date": "2026-10-20",
"horizon_days": 25, "issued_at": "2026-09-25T00:30:00Z", "model_version": "dam-30d-v2.2",
"unit": "Rs/MWh", "price_cap_rs_mwh": 10000, "count": 96 }
}Block 1 is 00:00–00:15 IST (IEX numbering); target_ts is the block start in UTC. Prices are bounded to 0 and the cap and given to ₹0.1; a value within ₹10 of the cap is the cap. meta.product is dam_forecast_30d, gdam_next_day or rtm_next_day. All three markets are issued once a day in the morning (IST), RTM before the day-ahead auction; an afternoon RTM update after the day-ahead results is being added. 404 no_forecast when no issue covers the date; 422 invalid_date or invalid_issue.
/developer/v1/forecast/iex/{dam,gdam,rtm}/hourlyGrowth · EnterpriseThe 24 hours of the same delivery day, with the column names of the hourly CSV files. DAM: median_price_rs_mwh, expected_price_rs_mwh, low_price_rs_mwh, high_price_rs_mwh, probability_at_price_cap. G-DAM: gdam_median_rs_mwh, gdam_low_rs_mwh, gdam_high_rs_mwh. RTM: rtm_median_rs_mwh, rtm_low_rs_mwh, rtm_high_rs_mwh.
Same date and issue parameters as /blocks; target_ts is the start of the hour in UTC. The DAM hourly median and range are computed for the hour as a whole (they are not the average of four block quantiles); its expected price and cap probability, and every G-DAM and RTM value, are the averages of the hour's four blocks.
/developer/v1/forecasts/{dam,rtm,outlook,vintages}Student · Pro · Starter · Growth · Enterprise (see the plan table)The forecast archive: every DAM, RTM and G-DAM forecast exactly as issued, never recomputed. /forecasts/dam is the next-day DAM forecast for a delivery day, /forecasts/rtm the RTM next-day forecast (variant=day_ahead, the default) or the rolling intraday forecast, /forecasts/outlook the D+1 to D+14 DAM outlook (p10/p50/p90 blocks), and /forecasts/vintages any archived vintage as it stood at as_of.
delivery_datestring/dam, /rtm and /vintages. Default: the newest issued.from · daysstring · integer/outlook: the first IST delivery day (default tomorrow) and how many days, 1 to 14.as_ofstringformatstringdefault: jsonjson, csv or xlsx: the desk block sheet with IST time ranges and p10/p50/p90 in Rs/MWh and Rs/kWh.These routes carry p10, p50 and p90 per block. Student and Pro keys receive 24 hourly rows, each the mean of its four blocks; Starter, Growth and Enterprise receive the 96 blocks. Calls count against the plan's monthly api_calls quota (Starter 50,000, Growth 500,000); past it the route answers 429 with resets_at. For the full percentile range, the cap probability and the hourly CSV columns, use the /forecast/iex/* routes above.
/forecasts/rtm?variant=day_ahead serves the RTM next-day forecast issued before the day-ahead auction, about 06:25 IST on the day before delivery (archive product next_day, variant pre_auction). It replaced the RTM day-ahead model on 7 Oct 2026. Requests that look back to before then get what was issued then: an as_of before 2026-10-07T00:00+05:30, or a delivery day before 27 Sep 2026, returns the retired model's forecast as issued. meta.product, meta.variant and meta.model_version say which forecast you received. The response shape and quotas are unchanged.