Skip to content
Teleport

Listing devices

Retrieve a list of all devices in your organization. This route is rate limited to 10 requests per 5 minutes per API key. It uses pagination with 100 results per page.


REQUEST
method + URL
GET https://api.teleport.withthegrid.com/v2/device/
query string (in TS)
{
offset?: string;
}
query string details
offset?
Is used for pagination, see https://teleport.withthegrid.com/api/#pagination
RESPONSE
successful responses
200
List of devices
body for status 200 (in TS)
{
devices: {
hashId: string;
name: string;
cloudApi: "READ" | "READ_WRITE";
reportingInterval: number;
dataForwarding: boolean;
assets: {
type: string;
category: "solar" | "wind" | "meter" | "battery" | "heat" | "irradiance" | "ev" | "misc";
identifier: string;
nominalActivePower: number | null;
}[];
controllers: {
type: string;
identifier: string;
schedule: (ReduceProductionPower | LimitPower)[] | null;
}[];
}[];
}
details for body status 200 (in TS)
devices[].cloudApi
"READ" means that the device is visible in the Teleport Cloud API, but requests to schedule asset commands or setting asset parameters for them will be rejected. "READ_WRITE" means that scheduling asset commands and setting asset parameters is allowed.
devices[].reportingInterval
In seconds. Applies to the default report type of each asset, like "solarPower", "windPower" and "batteryPower". Does not apply to auxilary reports like "batteryPower.flash".
devices[].dataForwarding
Whether data forwarding is enabled for this device. See https://teleport.withthegrid.com/data-forwarding/ for more information.
devices[].assets[].nominalActivePower
Total nominal active power of the asset in W, as configured by us. When possible, this value is verified with data from the asset. Can be null if not available.
devices[].assets[].schedule
The latest schedule sent in through our cloud API confirmed by this device. Instructions coming from control loops or the local API are not included.
devices[].controllers[].schedule
The latest schedule sent in through our cloud API confirmed by this device. Instructions coming from control loops or the local API are not included.
error responses (next to generic errors)
400 { key: "invalid_offset" }
The provided offset query parameter is invalid

Schedule per device

Until April 2024 we returned schedules per device instead of per asset.


REQUEST
method + URL
GET https://api.teleport.withthegrid.com/v1/device/
query string (in TS)
{
offset?: string;
}
query string details
offset?
Is used for pagination, see https://teleport.withthegrid.com/api/#pagination
RESPONSE
successful responses
200
List of devices
body for status 200 (in TS)
{
devices: {
hashId: string;
name: string;
cloudApi: "READ" | "READ_WRITE";
reportingInterval: number;
dataForwarding: boolean;
schedule: ({
type: 'limitProductionPower';
percentage: number;
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
} | {
type: 'reduceProductionPower';
powerReduction: number;
startAt: Date;
endAt: Date;
controlIdentifiers?: string[];
} | {
type: 'limitPower';
feedIn: number | null;
consume: number | null;
startAt: Date;
endAt: Date;
controlIdentifiers?: string[];
} | {
type: 'setBatteryOperation';
operation: {
dispatchPower: {
activePower: number;
} | null;
deliverFCR: {
maxRate: number;
} | null;
chargeToState: {
percentage: number;
} | null;
};
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
} | {
type: 'setEVOperation';
operation: {
limit: {
power?: number | null;
current?: number | null;
} | null;
};
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
})[] | null;
assets: {
type: string;
identifier: string;
nominalActivePower: number | null;
}[];
}[];
}
details for body status 200 (in TS)
devices[].cloudApi
"READ" means that the device is visible in the Teleport Cloud API, but requests to schedule asset commands or setting asset parameters for them will be rejected. "READ_WRITE" means that scheduling asset commands and setting asset parameters is allowed.
devices[].reportingInterval
In seconds. Applies to the default report type of each asset, like "solarPower", "windPower" and "batteryPower". Does not apply to auxilary reports like "batteryPower.flash".
devices[].dataForwarding
Whether data forwarding is enabled for this device. See https://teleport.withthegrid.com/data-forwarding/ for more information.
devices[].schedule
The latest schedule sent in through our cloud API confirmed by this device. Instructions coming from control loops or the local API are not included.
devices[].schedule[](type='limitProductionPower').percentage
Non-negative and <= 100. 0 will turn power production off, 100 will not curtail it at all.
devices[].schedule[](type='limitProductionPower').assetIdentifiers?
When specified, the Teleport will only send the command to inverters or turbines whose identifier is in the array. Has no use case for Teleports that are connected to a single inverter or turbine.
devices[].schedule[](type='reduceProductionPower').powerReduction
In W and nonnegative.
devices[].schedule[](type='reduceProductionPower').controlIdentifiers?
When specified, the Teleport will only send the command to active control loops whose identifier is in the array. Has no use case for Teleports that have a single active control loop.
devices[].schedule[](type='limitPower').feedIn
In W and nonnegative
devices[].schedule[](type='limitPower').consume
In W and nonnegative
devices[].schedule[](type='limitPower').controlIdentifiers?
When specified, the Teleport will only send the command to active control loops whose identifier is in the array. Has no use case for Teleports that have a single active control loop.
devices[].schedule[](type='setBatteryOperation').operation.dispatchPower.activePower
In W. Positive means discharging, negative charging.
devices[].schedule[](type='setBatteryOperation').operation.deliverFCR.maxRate
In W and non-negative.
devices[].schedule[](type='setBatteryOperation').operation.chargeToState.percentage
Non-negative and <= 100.
devices[].schedule[](type='setBatteryOperation').assetIdentifiers?
When specified, the Teleport will only send the command to batteries whose identifier is in the array. Has no use case for Teleports that are connected to a single battery.
devices[].schedule[](type='setEVOperation').operation.limit.power?
In W. Active power for AC chargers. For non-bidirectional chargers this value should not be positive. Use null or leave the property out to indicate that no limit should be set.
devices[].schedule[](type='setEVOperation').operation.limit.current?
In A. For non-bidirectional chargers this value should not be positive. Use null or leave the property out to indicate that no limit should be set. This is the phase current. In wye configurations it is the same as the line current. For delta configurations the phase current has to be multiplied by √3 to get the line current
devices[].schedule[](type='setEVOperation').assetIdentifiers?
When specified, the Teleport will only send the command to batteries whose identifier is in the array. Has no use case for Teleports that are connected to a single battery.
devices[].assets[].nominalActivePower
Total nominal active power of the asset in W, as configured by us. When possible, this value is verified with data from the asset. Can be null if not available.
error responses (next to generic errors)
400 { key: "invalid_offset" }
The provided offset query parameter is invalid