Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Network Sustainability Analytics: API Endpoints and Parameters

Use the Network Sustainability Analytics APIs to programmatically access sustainability data and configure supported settings.

This topic describes the supported Network Sustainability Analytics API endpoints, request parameters, and HTTP status codes. Use this information to construct API requests and interpret API responses.

For information about accessing Data Center Assurance sustainability data using APIs, API request authentication, and API token access permissions, see Access Data Center Assurance Using APIs.

Supported API Endpoints

Supports API requests for the following resources:

  • Energy Settings

  • Traffic Settings

  • Sites Summary Metrics

  • Non-Usage Emissions

  • Forecasted Power

  • Historical Metrics

  • Savings Summary

  • Savings by Recommendation Type

Each resource type is scoped to either an organization (org_id) or a specific site (site_id).

For example:

  • Organization:

    GET /api/v1/sustainability/orgs/<org-id>/energy_settings

  • Site:

    GET /api/v1/sustainability/sites/<site-id>/energy_settings

The settings endpoints support GET, POST, and PUT methods for configuration changes.

Table 1 lists the API endpoints supported for each resource type.

Table 1: Supported API Endpoints
Resource Type API Endpoints
 

Organization

Sites

Energy Settings

  • GET /api/v1/sustainability/orgs/<org-id>/energy_settings

  • POST /api/v1/sustainability/orgs/<org-id>/energy_settings

  • PUT /api/v1/sustainability/orgs/<org-id>/energy_settings

  • GET /api/v1/sustainability/sites/<site-id>/energy_settings

  • POST /api/v1/sustainability/sites/<site-id>/energy_settings

  • PUT /api/v1/sustainability/sites/<site-id>/energy_settings

Traffic Settings

  • GET /api/v1/sustainability/orgs/<org-id>/traffic_settings

  • POST /api/v1/sustainability/orgs/<org-id>/traffic_settings

  • PUT /api/v1/sustainability/orgs/<org-id>/traffic_settings

  • GET /api/v1/sustainability/sites/<site-id>/traffic_settings

  • POST /api/v1/sustainability/sites/<site-id>/traffic_settings

  • PUT /api/v1/sustainability/sites/<site-id>/traffic_settings

Sites Summary Metrics

GET /api/v1/sustainability/jei-core/stats/orgs/<org-id>/sites-summary

 -

Non-Usage Emissions

 GET /api/v1/sustainability/jei-core/stats/orgs/<org-id>/nonusage-emissions GET /api/v1/sustainability/jei-core/stats/sites/<site-id>/nonusage-emissions

Forecasted Power

POST /api/v1/sustainability/jei-core/stats/orgs/<org-id>/forecasted-power

 POST /api/v1/sustainability/jei-core/stats/sites/<site-id>/forecasted-power

Historical Metrics

 POST /api/v1/sustainability/jei-core/stats/historical/orgs/<org-id>/metrics POST /api/v1/sustainability/jei-core/stats/historical/sites/<site-id>/metrics

Savings Summary

 GET /api/v1/sustainability/jei-recommender/orgs/<org-id>/savings/summary GET /api/v1/sustainability/jei-recommender/orgs/<org-id>/sites/<site-id>/savings/summary

Savings by Recommendation Type

 POST /api/v1/sustainability/jei-recommender/orgs/<org-id>/savings/summary-by-recommendation-type POST /api/v1/sustainability/jei-recommender/orgs/<org-id>/sites/<site-id>/savings/summary-by-recommendation-type

Supported Parameters

You can add parameters to modify the output of your API request as per your requirements.

Table 2: Supported Query and Path Parameters
Parameter Value Description Example
org_id Organization ID Path parameter that identifies the organization to query or configure.
Note: Required parameter on all organization-scoped endpoints.
 GET /api/v1/sustainability/orgs/org_id/energy_settings
site_id Site ID Path parameter that identifies the site to query or configure.
Note: Required parameter on all site-scoped endpoints.
 GET /api/v1/sustainability/sites/site_id/energy_settings
from Epoch milliseconds Start of the time range.
Note: Required parameter on sites-summary, forecasted-power, historical metrics, and savings summary endpoints.
 GET .../sites-summary?from=1753948800000
to Epoch milliseconds End of the time range.
Note: Required with from parameter on the same endpoints.
 GET .../sites-summary?to=1753949700000
sort Metric name Sort site summary results by the specified metric.
Note:

This parameter is optional and is supported only on the Sites Summary Metrics endpoint.

Allowed metrics:

  • power

  • cost

  • emission

  • total_throughput_bytes

  • energy_savings_kwh

  • achieved_energy_savings_kwh

Each metric can be prefixed with a hyphen (-) to sort the results in descending order.

 GET .../sites-summary?sort=-power
limit Number Maximum number of items to return.
Note: This parameter is optional and is supported only on the Sites Summary Metrics endpoint. The default limit is 50.
 GET .../sites-summary?limit=10
offset Number Number of items to skip before returning results.
Note: This parameter is optional and is supported only on the Sites Summary Metrics endpoint. The default is 0
 GET .../sites-summary?offset=2

Some endpoints also accept parameters in the request body for POST and PUT requests.

Table 3: Supported Request Body Fields
Endpoints Field Description

Forecasted, Power, Historical Metrics

 interval_type Granularity of the data: 1mo (monthly) or 1d (daily).
Historical Metrics aggregated Boolean.

true returns a single aggregated value

false (default) returns time series data

Energy Settings

(POST/PUT)

  • settings.carbon_intensity

  • settings.unit_power_cos

  • settings.currency

  • settings.features.sustainability

  • settings.features.sustainability_pa

  • settings.features.enabled_for_application

Energy settings values.

Some fields accept only specific values. Accepted values are:

  • settings.features.sustainability and settings.features.sustainability_pa—"true", "false"
  • settings.features.enabled_for_application—Array of applications. Currently only "dca" is supported; for example ["dca"].

features is required for organization scope and not allowed for site scope.

All listed fields are required for POST requests and optional for PUT requests.

Traffic Settings

(POST/PUT)

  • traffic_settings.low

  • traffic_settings.high

 Traffic threshold values; high must be greater than low.

Savings by Recommendation Type

 action_type Optional.

Filters results to recommendation types whose name contains this substring. The default is ALL (no filtering).
Note:

The Savings Summary and Savings by Recommendation Type endpoints always return HTTP 200 status code.

For these endpoints, request validation errors are reported in the response body as status.status = 400 and status.message and instead of as an HTTP error status code.

See the endpoint description in the Swagger specification for the exact list of possible error messages.

REST API HTTP Status Codes

After you send as API request, the API returns a response with one of the following HTTP status codes.

Table 4: HTTP Status Codes
Status Description
200

OK.

The API successfully processed the request and returned a response.
204

No Content.

The request succeeded, but the response does not contain a body. This status code is returned by the DELETE operations for the Energy Settings and Traffic Settings endpoints.
400

Bad Request.

The API endpoint exists but the request syntax or payload is invalid.

401

Unauthorized.

The authentication toward the API failed.

You receive this code if the authentication token is invalid or is not sent in the required format. Verify your authentication information.
403

Forbidden.

Authentication succeeded, but the caller does not have permission to access the requested organization, site, or resource. Access is also enforced at the upstream gateway or service layer in front of sustainability service.
404

Not found.

The requested Energy Settings or Traffic Settings resource does not exist for the specified organization or site. This status code can also be returned when the requested Forecasted Power resource is not available.
405

Method Not Allowed.

The Energy Settings or Traffic Settings endpoint received an HTTP method other than GET, POST, or PUT.
500

Internal Server Error.

The API encountered an unexpected condition that prevented it from fulfilling the request.
503

Service Unavailable.

This status code is returned by Forecasted Power and Historical metrics endpoints when interval_type=1d is requested but the daily data source is not configured for the deployment.