Sunrun logo
API docs by Redocly

Customer OnDemand API (1.0.0)

Download OpenAPI specification:Download

Authentication

APIKey

API Key

Security Scheme Type: API Key
Header parameter name: x-api-key

Telemetry APIs

Start telemetry job

Initiate the telemetry job from the Vendor's API.

To check the status of the job use the /status endpoint.

Caching

This endpoint will return the same receipt ID the same payload is provided more than one time and if met the following conditions:

1. The request must be within the last 15 minutes for a complete status or within the last minute for a pending status.

1.1. If the request is pending for more than 1 minute, a new receipt ID will be generated. Reason: The previous request must likely be a stuck request.

1.2. If the request is complete status but overlapped the 15min window, a new receipt ID will be generated. Reason: There is another interval available.

1.2.1. Example #1: The previous request was made at 10:55 and the current request is made at 11:05, the request is within the 15min window, but at 11:00 there is another interval available, so we should not reuse it.

1.2.2. Example #2: The previous request was made at 11:02 and the current is made 11:14, in this case, we should reuse the previous request, because the current request is within the 15min window and there is no other interval available.

2. The access token should be the same for all the previous requests.

2.1. The access token returned in this endpoint is the same for all the requested telemetry types, which means, if there are multiple telemetry types requested and the matching receipt IDs have different access tokens, we can only reuse the ones with the same access token, because we can't return multiple access tokens in the response.

2.1.1. Example #1: The previous request was made with type production and the current request with type all, in this case, we can reuse the receipt ID for production and assign the same access token to the other telemetry types.

2.1.2. Example #2: There are two previous requests, one with type production and the other with type power, both with different access tokens, in this case, we can't reuse both, so we reuse the first one, generate a new receipt ID for the second one (power) and assign the same access token reused from the first one to the new generated receipt ID.

2.1.3. Example #3: There is one previous request with type all, and the current request is type production, in this case, we can reuse the receipt ID, if a subsequent request is made with type power, we can also reuse it.

Authorizations:
APIKey
Request Body schema: application/json
required

Telemetry Request Body

siteId
required
string
type
string
Default: "all"
Enum: "power" "production" "site" "storage_soc" "all"

Telemetry type.

aggregation
any
Default: "today"

Aggregation level for telemetry data

Value: "today"
unit
string
Enum: "kwh" "kw"

Unit for telemetry data

object

Time range for telemetry data

cache
boolean
Default: true

Set to false if you always want to fetch the latest data from the vendor API

loadMode
string
Default: "delta"
Enum: "delta" "full"

Load mode for telemetry data,

  • 'delta': Fetch only the new data since the last request (default)
  • 'full': Fetch all data available from the vendor API in 2-day intervals

The 'delta' mode is recommended for most use cases. The 'full' mode is useful for the initial data load or when the data is missing or corrupted.

Responses

Request samples

Content type
application/json
Example
{
  • "siteId": "000000000",
  • "type": "production",
  • "aggregation": "today",
  • "range": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "PENDING",
  • "accessToken": "<access_token>",
  • "receiptIds": [
    ]
}

Get telemetry job status

Check if the telemetry data is already available, if yes, the data is also returned as part of the response.

Authorizations:
APIKey
Request Body schema: application/json
required

Telemetry Job Status Request Body

receiptId
required
string

The receipt id generated in the /telemetry endpoint.

accessToken
required
string

The access key generated along with the receipt id in the /telemetry endpoint

type
string
Enum: "power" "production" "storage_soc" "site"

The type of telemetry data to retrieve.

Responses

Request samples

Content type
application/json
{
  • "accessToken": "<access_token>",
  • "receiptId": "<receipt_id>"
}

Response samples

Content type
application/json
Example
{
  • "status": "PENDING",
  • "type": "production",
  • "aggregation": "today"
}