The capture service allows collecting waveform data for configured input channels.

Basic Usage

GET /capture&i returns information about the channels for which waveform data can be captured. The returned object might look like this:

  "channels": {
    "0": {"name": "L1", "unit": "V"},
    "1": {"name": "L2", "unit": "V"},
    "4": {"name": "S1", "unit": "A"}

This response indicates that three channels are available. The meter-internal channel numbers are 0, 1, and 4. As the name values indicate, those channels correspond to meter inputs L1, L2, and S1, respectively. The first two channels return samples as volts (V) and the third returns samples as amperes (A).

GET /capture?n&d=1e-3&c=0&c=4 initiates a capture for 1ms of samples on channels 0 and 4 and returns a cookie (token) to be used to retrieve the capture samples. The response for this request might look like this:

{"state": "armed", "cookie": 1875353535}

State armed indicates that the meter successfully processed the capture request and is waiting for the trigger to occur. Cookie 1875353535 is a random integer to be used when retrieving the sampled data, as shown next.

GET /capture?n=1875353535 can now be used to fetch the samples. The response might look as shown below:

    "state": "full", "ts_freq": 1000000, "first_sample": "1619637288.061",
    "ch_mask": [17, 0],
    "r": [
      {"t": 495514564, "d": [135.059]},
      {"t":        82, "d": [-0.0146239]},
      {"t":      1354, "d": [105.454, -0.00731193]}

State full indicates that the capture buffer is full and therefore the response contains sample values. The frequency of the counter used to generate the timestamps is 1MHz ("ts_freq": 1000000) and the realtime Unix timestamp of the first sample is 28 April 2021, 19:14:48 UTC (first_sample": "1619637288.061"). The ch_mask member is an array of 32-bit integers. If a bit is set in this mask, data for that channel is included in the response. In our case, the channel mask has only bits 0 and 4 set in the first integer (17), indicating that channels 0 and 4 are contained in the sampled data (in order from smallest to largest channel numbers). The timestamp t of the first sample is 495514564 and the subsequent samples were acquired 82 and 1354 timestamp ticks after the corresponding previous sample. Thus, the reconstructed sample values for the channels are:

Timestamp [µs] Channel 0 value [V] Channel 1 value [A]
495514564 135.059
495514646 -0.01462390
495516000 105.454 -0.00731193

Note how the sample values are returned strictly in order from lowest number to highest numbered channel: 0, 4, 0, 4. Also note how there is a separate entry in the result array r for each unique timestamp. Each data array (d) may have just a single entry or multiple entries if there are multiple sample values with the same timestamp.

Python Example

A Python program illustrating the use of this service can be found here. This program takes advantage of class egauge.webapi.device.Capture to handle the details of encoding the HTTP requests and decoding the responses.

Capture waveform data

query Parameters
integer >= 0

The channel number to use as the trigger.


The trigger mode to use. any triggers immediately, rise triggers when a rising edge crosses the trigger level, fall triggers when a falling edge crosses the trigger level, gt triggers when the trigger channel's sample value is greater than the trigger level, and lt triggers when it is less than the trigger level.

Enum: "any" "rise" "fall" "gt" "lt"

The trigger level.


If present, this query parameter cancels a pending capture and resets the state to available. If a value for query parameter n is also specified, only the matching capture is canceled. Otherwise, any pending capture is canceled.

number >= 0

Trigger timeout in milliseconds. After starting a capture, if the trigger condition is not satisfied within this timeout period, the capture is auto-triggered.

integer >= 0

Channel number to be captured. This query parameter can be specified multiple times to capture multiple channels. If not specified, all configured channels are captured by default.


Capture duration in seconds. If less than or equal to 0, the maximum number of samples are acquired. This maximum is implementation dependent but, generally, a fixed size buffer is used to store all samples of all channels, so the more channels are being captured, the lower the upper bound for this value. If the value is greater than this upper bound, it is automatically capped at that value.


Return a channel info object, describing each channel that may be captured, its name and its physical unit.

integer >= 0

Non-blocking operation. If the query parameter has no value or an empty string value, this requests that a capture is initiated without waiting for the result to be available (asynchronous operation). In this case, a cookie object is returned which contains a token. The token can be used in subsequent requests to fetch the result of the capture or to check on its status.

If a value is specified, it must be a token returned in an earlier cookie object response. In this case, the capture status is reported via a progress object if it is still pending or a capture result object if the capture is complete.


Pre-trigger duration in seconds. Specifies how many seconds of samples before the trigger point should be acquired. If omitted, this defaults to 0 seconds of pre-trigger data.


If present, this query parameter requests that the data should be returned as plain text rather than as JSON.


If present, this query parameter requests that the sample values should be returned as raw (digital) sample values rather than as values converted to the channel's physical unit.


Capture response.


Unauthorized response.

Request samples
Response samples
  • "channels": {
  • "error": "Error message (present if an error occurred)."