Lookups Overview

Certain types of Property Keys have a large set of corresponding values and/or values that change frequently over time. Examples include property keys that hold wholesale energy price indexes that change hourly, or monthly retail electricity fuel cost adjustment rates. In some cases, electricity rates can vary daily (New York) or even hourly (specialty variable rate plans).

Whenever we need to track data that can have a large number of values, values tied to a date range, or values that update at least monthly, we typically use a special type of Property Key called a "Lookup". These Property Keys include a lookup table to store their values (hence the name). You can identify when a Property Key has a lookup table attached because its dataType field has a value of LOOKUP.

Use the Lookup endpoints to query lookup table values directly or retrieve summary statistics for a lookup table.

Choose a Lookup endpoint

List Lookup Values

Retrieve lookup table values for a LOOKUP Property Key, optionally filtered by sub-property and date range.

Get Lookup Stats

Retrieve summary statistics such as date coverage, lookup count, mean value, and last updated date.

Data Definitions

Lookup Value

A lookup value (resource type PropertyLookup) has the following data structure:

Name	Type	Fields	Description
lookupId	Integer	M	The unique ID for this lookup value entry in the lookup table
propertyKey	String	M	The unique name for the property this lookup belongs to
subPropertyKey	String	M	Sub-property this lookup value applies to (when needed, e.g., wholesale index node or zone)
fromDateTime	DateTime	M	Date Range - from date time for this value
toDateTime	DateTime	M	Date Range - to date time for this value
bestValue	Decimal	M	Best kWh/kW price for the property key for the date range
bestAccuracy	Decimal	M	Reserved for future use
actualValue	Decimal	M	Actual kWh/kW price for the property key for the date range
lseForecastValue	Decimal	M	kWh/kW price forecasted by the utility for the property key for the date range
lseForecastAccuracy	Decimal	M	Reserved for future use
forecastValue	Decimal	M	kWh/kW price forecasted by Arcadia for the property key for the date range based on previous values
forecastAccuracy	Decimal	M	Reserved for future use

Get Property Lookup Values

Use the following call to get the lookup table values for a specific Property Key. If a date range is not specified, it defaults to the last 72 hours.

Resource URI

GET /rest/public/properties/{propertyKey}/lookups

Request Parameters

Name	Type	Description
propertyKey	String	Property key name
subPropertyKey	String	Subproperty key name (Optional)
fromDateTime	DateTime	Date range - from value (Optional)
toDateTime	DateTime	Date range - to value (Optional)

❗️
We recommend using fromDateTime in concert with toDateTime to avoid edge cases where an empty results array is returned.
If you supply a fromDateTime and do not explicitly pass a toDateTime it will default to midnight T00:00:00 of the current day.
When fromDateTime and toDateTime are not passed, the default behavior is to return 3 days (72 hours) of data entries at the lookup's cadence.

Example 1 - Get All Lookup Table Values for a Property Key

GET /rest/public/properties/hourlyPricingRealTimeERCOT/lookups

{
    "status": "success",
    "count": 384,
    "type": "PropertyLookup",
    "results": [
        {
            "lookupId": 19890442,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "AEN",
            "fromDateTime": "2017-11-04T00:00:00",
            "toDateTime": "2017-11-04T01:00:00",
            "bestValue": 0.01783,
            "bestAccuracy": 0,
            "actualValue": 0.01783,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        },
        {
            "lookupId": 19932102,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "CPS",
            "fromDateTime": "2017-11-06T18:00:00",
            "toDateTime": "2017-11-06T19:00:00",
            "bestValue": 0.04826,
            "bestAccuracy": 0,
            "actualValue": 0.04826,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        },
        {
            "lookupId": 19932109,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "HOUSTON",
            "fromDateTime": "2017-11-06T01:00:00",
            "toDateTime": "2017-11-06T02:00:00",
            "bestValue": 0.01946,
            "bestAccuracy": 0,
            "actualValue": 0.01946,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Example 2 - Get a Specific Sub-key's Lookup Values for a Property Key

GET /rest/public/properties/hourlyPricingDayAheadERCOT/lookups?subKeyName=CPS

{
    "status": "success",
    "count": 48,
    "type": "PropertyLookup",
    "results": [
        {
            "lookupId": 19932084,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "CPS",
            "fromDateTime": "2017-11-06T00:00:00",
            "toDateTime": "2017-11-06T01:00:00",
            "bestValue": 0.01799,
            "bestAccuracy": 0,
            "actualValue": 0.01799,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        },
        {
            "lookupId": 19932085,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "CPS",
            "fromDateTime": "2017-11-06T01:00:00",
            "toDateTime": "2017-11-06T02:00:00",
            "bestValue": 0.01777,
            "bestAccuracy": 0,
            "actualValue": 0.01777,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        },
        {
            "lookupId": 19932086,
            "propertyKey": "hourlyPricingDayAheadERCOT",
            "subPropertyKey": "CPS",
            "fromDateTime": "2017-11-06T02:00:00",
            "toDateTime": "2017-11-06T03:00:00",
            "bestValue": 0.0176,
            "bestAccuracy": 0,
            "actualValue": 0.0176,
            "lseForecastValue": null,
            "lseForecastAccuracy": null,
            "forecastValue": null,
            "forecastAccuracy": null
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Get Property Lookup Stats

This endpoint provides summary statistics for a given property key (only LOOKUP data type property keys are relevant here). It returns statistics such as minFromDateTime, maxToDateTime, lookupCount, meanValue, totalDuration, and lastUpdatedDate.

Resource URI

GET /rest/public/properties/{propertyKey}/stats

Request Parameters

Name	Type	Description
propertyKey	String	Property key name

Response Object

Name	Type	Description
keyName	String	The unique name (key) for this Property.
maxFromDateTime	DateTime	The final instance in the corresponding lookup's recorded history. This should align with the `closed` field.
maxToDateTime	DateTime	The latest instance in the corresponding lookup's recorded history.
meanValue	Decimal	The mean cost value of all recorded lookup entries.
meanDuration	Integer	The computed average duration, in minutes, that a lookup entry remains effective. Calculated as `totalDuration` ÷ `lookupCount` across the full lookup dataset for the Property Key.
missingDuration	Integer	The total duration in minutes (within the period from `minFromDateTime` to `maxToDateTime`) for which lookup data is missing.
lastUpdatedDate	DateTime	The last captured update for this lookup.
expectedNextUpdateDate	DateTime	Next expected update if available, otherwise `null`.
minFromDateTime	DateTime	The first instance in the corresponding lookup's recorded history.
lookupCount	Integer	The number of recorded entries in the lookup's history.
totalDuration	Integer	The total duration of time, in minutes, covered by all lookup entries.
closed	DateTime	If the property key was closed/retired, the date when that occurred, otherwise `null`.

Example 3 - Get Lookup Stats

GET /rest/public/properties/realTimeURGPriceSCETOU8D2KV/stats?fields=ext

{
    "status": "success",
    "count": 1,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "realTimeURGPriceSCETOU8D2KV",
            "maxFromDateTime": null,
            "maxToDateTime": "2026-02-25T00:00:00",
            "meanValue": 0.079361273,
            "meanDuration": 59,
            "missingDuration": 11880,
            "lastUpdatedDate": "2026-02-24T09:01:01",
            "expectedNextUpdateDate": null,
            "minFromDateTime": "2016-01-01T00:00:00",
            "lookupCount": 88796,
            "totalDuration": 5327640,
            "closed": null
        }
    ]
}