Query Metrics with the API

Use the Edge Delta API to query metric timeseries data programmatically.

3 minute read

The Edge Delta metrics API returns timeseries data for any metric in your organization. Use it to build custom dashboards, automate alerting workflows, or integrate Edge Delta metrics with external tools.

Prerequisites

You need:

Your Organization ID
An API Token with appropriate permissions

Endpoint

GET /v1/orgs/{org_id}/metrics_v2/graph

Query Syntax

The query parameter uses a metric-specific query format:

aggregation:metric_name{filter} [by {field1,field2}] [.rollup(seconds)]

Component	Required	Description
`aggregation`	Yes	How to combine data points: `sum`, `avg`, `min`, `max`, `count`, `last`, `median`, `p50`, `p75`, `p90`, `p95`, `p99`
`metric_name`	Yes	Exact metric name, such as `ed.buffer.disk.bytes`. See Metrics List for available metrics.
`{filter}`	Yes	Filter expression. Use `{*}` to match all data, or specify field conditions.
`by {fields}`	No	Group results by one or more fields.
`.rollup(seconds)`	No	Aggregation window in seconds.

Filter Syntax

Filters go inside the curly braces:

Pattern	Example	Description
Match all	`{*}`	No filtering
Exact match	`{ed.tag:my-pipeline}`	Match a specific pipeline tag
Quoted value	`{ed.tag:"my pipeline"}`	Match a value containing spaces
Wildcard	`{ed.tag:prod*}`	Prefix matching
OR	`{ed.tag:(prod OR staging)}`	Match multiple values
NOT	`{-(ed.tag:dev)}`	Exclude a value
Multiple fields	`{ed.tag:prod host.name:web-1}`	AND (implicit)

Examples

Basic Query

Query the average disk buffer size over the last hour:

curl -G 'https://api.edgedelta.com/v1/orgs/<ORG_ID>/metrics_v2/graph' \
  --data-urlencode 'query=avg:ed.buffer.disk.bytes{*}' \
  --data-urlencode 'lookback=1h' \
  -H 'X-ED-API-Token: <API_TOKEN>'

Filter by Pipeline

Query successful uploads for a specific pipeline:

curl -G 'https://api.edgedelta.com/v1/orgs/<ORG_ID>/metrics_v2/graph' \
  --data-urlencode 'query=sum:ed.pipeline.node.upload.successful{ed.tag:my-pipeline}' \
  --data-urlencode 'lookback=1h' \
  -H 'X-ED-API-Token: <API_TOKEN>'

Group by Host

Query buffer queue depth grouped by host with a 60-second rollup:

curl -G 'https://api.edgedelta.com/v1/orgs/<ORG_ID>/metrics_v2/graph' \
  --data-urlencode 'query=max:ed.buffer.disk.items{*} by {host.name}.rollup(60)' \
  --data-urlencode 'lookback=30m' \
  -H 'X-ED-API-Token: <API_TOKEN>'

Specific Time Range

Use from and to instead of lookback for an exact time range:

curl -G 'https://api.edgedelta.com/v1/orgs/<ORG_ID>/metrics_v2/graph' \
  --data-urlencode 'query=avg:ed.buffer.disk.bytes{*}' \
  --data-urlencode 'from=2025-01-15T00:00:00.000Z' \
  --data-urlencode 'to=2025-01-15T01:00:00.000Z' \
  -H 'X-ED-API-Token: <API_TOKEN>'

Response Format

The API returns timeseries data grouped by the fields in your by clause:

{
  "from": "2025-01-15T00:00:00Z",
  "to": "2025-01-15T01:00:00Z",
  "window": "1m0s",
  "records": [
    {
      "values": ["my-pipeline", "worker-1"],
      "timeseries": [
        {"timestamp": "2025-01-15T00:01:00Z", "value": 1048576},
        {"timestamp": "2025-01-15T00:02:00Z", "value": 2097152},
        {"timestamp": "2025-01-15T00:03:00Z", "value": 3145728}
      ],
      "aggregate": {"value": 6291456}
    }
  ],
  "keys": ["ed.tag", "host.name"]
}

Field	Description
`from`	Start of the query window in ISO 8601 format
`to`	End of the query window in ISO 8601 format
`window`	The rollup window applied to the timeseries
`records`	One record per unique combination of `by` field values. When no `by` clause is used, returns a single record for the overall result.
`values`	The field values for this record, in the same order as `keys`. Only present in records when a `by` clause is used.
`timeseries`	Array of timestamp/value pairs. Missing intervals indicate no data for that period.
`aggregate`	The aggregation applied across the entire time range
`keys`	The field names corresponding to `values`. Present at the top level of the response when `by` is used; `null` otherwise.

Query Parameters

Parameter	Type	Description
`query`	string	Metric query expression (required)
`lookback`	string	Duration in Go format, such as `30m`, `1h`, `24h`. Use this or `from`/`to`.
`from`	string	Start time in ISO 8601 format
`to`	string	End time in ISO 8601 format

Common Metrics

For a full list of available metrics, see the Metrics List. Common metrics for monitoring pipeline health include:

Metric	Description
`ed.pipeline.node.read_bytes`	Bytes ingested by a node
`ed.pipeline.node.write_bytes`	Bytes output by a node
`ed.pipeline.node.upload.successful`	Successful destination uploads
`ed.pipeline.node.error`	Errors at a node
`ed.buffer.disk.bytes`	Disk buffer size in bytes
`ed.buffer.disk.items`	Items in the disk buffer queue