Skip to main content

Running Sandbox Dispatch Simulations

Voltus provides a sandbox environment for you to test standard dispatch scenarios. You must run and pass all dispatch scenarios in sandbox before Voltus will schedule production dispatches for your sites. A dispatch scenario is one or more dispatches being created and updated on sandbox.voltus.co.

For other uses of the sandbox environment that do not require a sandbox key see Sandbox Test Credentials.

Voltus will provide a Sandbox API key for use with sandbox.voltus.co. In the below requests, this will be called ${SANDBOX_API_KEY} as a placeholder.

You must monitor your systems to ensure they meet the “passing criteria” for each test. Voltus will not be able to monitor the curtailment output of your system and whether it matches expectations.

Reach out to api-support@voltus.co with any questions about creating a dispatch scenario.

Running Dispatch Scenarios​

For each dispatch scenario, you will specify a notification_time which is the time the dispatch scenario will start. You may also specify site names, site customer_location_ids, and program information if you wish.

To run a dispatch scenario, you will send a POST request to sandbox.voltus.co/2022-04-15/scenarios with a X-Voltus-API-Key header set to your sandbox key and a body specifying the scenario parameters. Example requests are shown for each dispatch scenario.

danger

If you create a scenario before the previous scenario has finished, the previous scenario will be overwritten, and all dispatches from that scenario will disappear.

You may add as many sites as desired. They must have unique names and customer_location_ids.

1. Basic Dispatch​

A basic dispatch. Start and end times will be provided immediately.

API Behavior: At <notification_time>, a dispatch will be issued that starts at <start_time> and has an end time of <end_time>.

Passing criteria: Your client sends a signal to both sites to be fully curtailed in time for the start time and begins to ramp up after the end time is reached.

Example curl request to run this dispatch scenario (all fields modifiable):

curl --request POST \
  --url https://sandbox.voltus.co/2022-04-15/scenarios \
  --header 'Content-Type: application/json' \
  --header "X-Voltus-API-Key: ${SANDBOX_API_KEY}" \
  --data '{
  "scenario_type": "basic",
  "notification_time": "2023-12-01T16:40:00Z",
  "start_time": "2023-12-01T16:50:00Z",
  "end_time": "2023-12-01T17:00:00Z",
  "sites": [
    {
      "name": "My Site",
      "customer_location_id": "democustomerlocationid",
      "commitment": 5
    },
    {
      "name": "Another Site",
      "customer_location_id": "democustomerlocationid2",
      "commitment": 50
    }
  ],
  "program": {
    "name": "A Program",
    "timezone": "PST",
    "market": "CAISO",
    "program_type": "capacity"
  }
}'

2. Ancillary Services Dispatch​

This emulates a typical ancillary service dispatch, where the end time is not initially provided and the start time is in the recent past. After ten minutes from the dispatch start time, the end time will be added as an update to the dispatch to end the dispatch immediately.

API Behavior: At <notification_time>, a dispatch will be issued that starts at <notification_time>. At <notification_time + 10 minutes>, a dispatch update will be issued that has an end time of <notification_time + 10 minutes>.

Passing criteria: At notification time, your client sends a signal to both sites to curtail immediately. When the dispatch update arrives 10 minutes later, your client sends a signal to the sites to ramp up immediately.

Example curl request to run this dispatch scenario (all fields modifiable):

curl --request POST \
  --url https://sandbox.voltus.co/2022-04-15/scenarios \
  --header 'Content-Type: application/json' \
  --header "X-Voltus-API-Key: ${SANDBOX_API_KEY}" \
  --data '{
    "scenario_type": "ancillary",
    "notification_time": "2023-12-01T16:40:00Z",
    "sites": [
        {
            "name": "My Site",
            "customer_location_id": "democustomerlocationid",
            "commitment": 5
        },
        {
            "name": "Another Site",
            "customer_location_id": "democustomerlocationid2",
            "commitment": 50
        }
    ],
    "program": {
        "name": "A Different Program",
        "timezone": "PST",
        "market": "CAISO",
        "program_type": "ancillary_services"
    }
}'

3. Back-to-Back Dispatches​

Two back-to-back dispatches. The first event start and end time will be provided immediately. Once the first event has begun, the second event’s start and end time will be provided.

API Behavior: At <notification_time>, a dispatch will be issued that starts at <notification_time> and has an end time of <notification_time + 10 minutes>. At <notification_time + 5 minutes>, a dispatch will be issued that starts at <notification_time + 10 minutes> and has an end time of <notification_time + 20 minutes>.

Passing criteria: Your client sends a signal to both sites to curtail immediately, stay curtailed through the first dispatch end time and the second dispatch start time, and only begin to ramp up after the second dispatch end time is reached.

Example curl request to run this dispatch scenario (all fields modifiable):

curl --request POST \
  --url https://sandbox.voltus.co/2022-04-15/scenarios \
  --header 'Content-Type: application/json' \
  --header "X-Voltus-API-Key: ${SANDBOX_API_KEY}" \
  --data '{
  "scenario_type": "back_to_back",
  "notification_time": "2023-12-01T16:40:00Z",
  "sites": [
    {
      "name": "My Site",
      "customer_location_id": "democustomerlocationid",
      "commitment": 5
    },
    {
      "name": "Another Site",
      "customer_location_id": "democustomerlocationid2",
      "commitment": 50
    }
  ],
  "program": {
    "name": "A Different Program",
    "timezone": "PST",
    "market": "CAISO",
    "program_type": "ancillary_services"
  },
  "sites2": [
    {
      "name": "My Site",
      "customer_location_id": "democustomerlocationid",
      "commitment": 5
    },
    {
      "name": "Another Site",
      "customer_location_id": "democustomerlocationid2",
      "commitment": 50
    }
  ],
  "program2": {
    "name": "A Program2",
    "timezone": "EST",
    "market": "NYISO",
    "program_type": "ancillary_services"
  }
}'

A Note on Timezones​

The body of the POST scenario request takes up to three times: notification_time, start_time, and end_time. These can be input with any timezone info. The GET dispatches endpoint will always return times converted to UTC. The program.timezone field does not affect the dispatch times and can be any string.

Example valid formats for POST scenario times:

  • 2023-11-29T20:40:00-08:00: PST (Pacific time in winter)
  • 2023-11-29T19:40:00-07:00: PDT (Pacific time in summer)
  • 2023-11-29T17:40:00-05:00: EST (Eastern time in winter)
  • 2023-11-29T16:40:00-04:00: EDT (Eastern time in summer)
  • 2023-11-29T16:40:00Z: UTC

Endpoints Available for Dispatch Simulations​

GET Dispatches/{id}​

Returns a list of dispatches (GET dispatches) or a dispatch (GET dispatches/{id}), which will change throughout the dispatch simulation.

GET/DELETE/POST Webhook​

Set up a webhook with sandbox.voltus.co and your sandbox credentials, the same way you would for api.voltus.co. Please follow our webhook tutorial or webhooks reference docs, replacing api.voltus.co with sandbox.voltus.co.

Once you’ve registered your webhook with POST webhooks and confirmed the webhook is returned from GET webhooks, Voltus will send a webhook request to your server every time a dispatch is issued or updated as part of a dispatch simulation, the same way a production dispatch would work.

Note: you will also need to register your webhook with production api.voltus.co before being ready for a Dispatch Verification.

GET Sites​

Returns the sites of the current (or most recent) dispatch scenario.

Note the site IDs may change for different scenarios.

Telemetry​

We do not support the telemetry endpoint for dispatch simulations at this time for dispatch simulation.