layout-3 layout-6 layout-1 layout-top
layout-top layout-6 layout-1

nvgrid

API Reference: v1/nvgrid.proto

Table of Contents

Services

NvGrid

NvGrid service provides a mechanism for bridging the gap between grid solutions that may implement OpenADR, Smart Grid, or other power utility integrations to actuate power utilization changes in datacenters operated by DPS.

SetLoadTarget

rpc SetLoadTarget(LoadTargetRequest) LoadTargetResponse

SetLoadTarget updates the future load target schedule using the given list of LoadTarget objects. Each LoadTarget defines the starting time, the optional ending time, and the target load. If the target load is null, the load target is reset to the data center default. If the ending time is omitted, the LoadTarget will remain in effect forever until another load target is scheduled. For a given point in time, the latest LoadTarget becomes the effective one. Because of this, updating a schedule can be achieved by setting a new schedule for the same duration with a different target, or setting the target to null to delete.

GetLoadSchedule

rpc GetLoadSchedule(GetLoadScheduleRequest) LoadSchedule

Returns the load schedules for some or all of the power feeds in a given interval

GetCurrentLoadTarget

rpc GetCurrentLoadTarget(.google.protobuf.Empty) GetCurrentLoadTargetResponse

Returns the current load target for each feed

GetMetadata

rpc GetMetadata(.google.protobuf.Empty) FeedMetadata

Returns metadata for each feed. This API can be used to discover all feeds defined in the data center and their default load caps.

RegisterWebhook

rpc RegisterWebhook(RegisterWebhookRequest) LoadTargetResponse

Registers a web hook that will receive notifications when power events happen.

UnregisterWebhook

rpc UnregisterWebhook(UnregisterWebhookRequest) LoadTargetResponse

Unregisters a previously registered webhook

GetStatus

rpc GetStatus(.google.protobuf.Empty) LoadTargetStatus

Returns the current status. This includes the current load targets and achieved load values for each power feed.

Messages

FeedMetadata

FeedMetadata object used to expose power thresholds and default constraints for all power feeds.

Field Type Description
metadata map FeedMetadata.MetadataEntry none

FeedMetadata.Entry

Metadata entry object used to expose power thresholds and default constraints for each power feed.

Field Type Description
feed_tag string none
power_minimum LoadValue none
power_maximum LoadValue none
default_constraint LoadValue none

FeedMetadata.MetadataEntry

Field Type Description
key string none
value FeedMetadata.Entry none

GetCurrentLoadTargetResponse

Response for GetCurrentLoadTarget containing current targets per feed

Field Type Description
load_targets map GetCurrentLoadTargetResponse.LoadTargetsEntry Map of feed tag to current load target for that feed

GetCurrentLoadTargetResponse.LoadTargetsEntry

Field Type Description
key string none
value LoadTarget none

GetLoadScheduleRequest

Specifies which load schedules to return in a given interval. The returned schedule starts with the LoadTarget that is active at the beginning of the interval and all future LoadTargets that will start before the interval’s end time.

Field Type Description
feed_tags repeated string The power feed tags for which to return load schedule. If empty, schedule for all feed tags will be returned
interval Interval The time interval for which to return the load schedule

Interval

Interval is a time interval. A missing element in the message implies an open interval.

Field Type Description
start_time google.protobuf.Timestamp none
end_time google.protobuf.Timestamp none

LoadSchedule

Load Schedule is an ordered-list of scheduled power constraint changes (LoadTargets).

Field Type Description
targets repeated LoadTarget none

LoadTarget

Describes how and when power targets should be applied.

Field Type Description
interval Interval The start_time is the the time in the future when the constraint should be activated. If omitted, the current local time is assumed. The end_time is the end time for this load target. If there are no overlapping load targets and if the end time is specified, the power will revert back to the default level at this time. If there is an overlapping target, the most recent overlapping target is used. If omitted, there is no end time.
load_constraint LoadValue The load constraint. If nil, it removes any constraints at the given time, which results in the system falling back to its default constraint.
load_target_strategy LoadTargetStrategy The strategy specifies what strategy will be used to achieve the desired load_constraint.
feed_tags repeated string Optional field to specify which power feeds the load target applies to. If none is given and if the datacenter has multiple power feeds, the load target will be applied to all power feeds.
correlation_id string Optional string that can be used by the caller to identify load targets. The correlation id can be at most 36 bytes, and can contain ascii letters/digits and “-”. It must be a unique id. If not provided, a UUID will be generated.

LoadTargetRequest

LoadTargetRequest contains one or more load targets in the future

Field Type Description
targets repeated LoadTarget The load targets

LoadTargetResponse

Response object that returns a status with a diagnostic message and a list of detailed messages.

Field Type Description
code LoadTargetResponse.StatusCode none
diag_msg string none
details repeated LoadTargetResponse.Detail none

LoadTargetResponse.Detail

Field Type Description
code LoadTargetResponse.StatusCode none
details google.protobuf.Any none
correlation_id string none

LoadTargetStatus

Current status of the system

Field Type Description
statuses map LoadTargetStatus.StatusesEntry none

LoadTargetStatus.FeedStatus

Field Type Description
current_load_target LoadValue Current power target set by a LoadTarget message
current_calculated_load LoadValue The current load as calculated by DPS, which may be different from current_load_target and the current actual in the data center
in_flight bool If true, DPS is still transitioning from one power target level to another
power_event_start_time google.protobuf.Timestamp The scheduled start time of the current power event in effect
correlation_id string The correlation id of the current active load target, if any.

LoadTargetStatus.StatusesEntry

Field Type Description
key string none
value LoadTargetStatus.FeedStatus none

LoadTargetStrategy

Describes how and when power targets should be applied.

Field Type Description
oneof strategy.best_effort bool If power constraints require shedding load, DPS will steal power from DPM-enabled jobs until the constraint is satisfied. If the constraint cannot be satisfied, DPS will steal as much power as it can, but leave the topology in a non-compliant state until jobs terminate. If power constraints are relaxed and if there are DPM-enabled jobs from which power was stolen, DPS will attempt to give more power to these jobs

LoadValue

LoadValue specifies the load with a unit..

Field Type Description
value double The value of the load
unit LoadValue.Unit The unit of the value.

RegisterWebhookRequest

Registers a webhook for events. This webhook will receive a Status message via an HTTP POST request.

Field Type Description
for_events repeated RegisterWebhookRequest.PowerEvent The list of events to subscribe to. If unspecified, then you will be subscribed to all power events.
url string The url to register for notifications.

UnregisterWebhookRequest

Unregister a webhook.

Field Type Description
url string none

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type

double		 double double float

float		 float float float

int32		 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int

int64		 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long

uint32		 Uses variable-length encoding. uint32 int int/long

uint64		 Uses variable-length encoding. uint64 long int/long

sint32		 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int

sint64		 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long

fixed32		 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int

fixed64		 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long

sfixed32		 Always four bytes. int32 int int

sfixed64		 Always eight bytes. int64 long int/long

bool		 bool boolean boolean

string		 A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode

bytes		 May contain any arbitrary sequence of bytes. string ByteString str

    Copyright © 2025  NVIDIA Corporation