API docs by Redocly

HyperDX External API (2.0.0)

Download OpenAPI specification:Download

API for managing HyperDX alerts and dashboards

Dashboards

Endpoints for managing dashboards and their visualizations

List Dashboards

Retrieves a list of all dashboards for the authenticated team

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create Dashboard

Creates a new dashboard

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string <= 1024 characters

Dashboard name.

required
Array of objects (TileInput) <= 500 items

List of tiles/charts to include in the dashboard.

tags
Array of strings <= 50 items [ items <= 32 characters ]

Tags for organizing and filtering dashboards.

Array of objects (FilterInput)

Dashboard filter keys to add to the dashboard and apply across all tiles

savedQuery
string or null

Optional default dashboard query to persist on the dashboard.

savedQueryLanguage
string (QueryLanguage)
Enum: "sql" "lucene"

Query language for the where clause.

Array of objects (SavedFilterValue)

Optional default dashboard filter values to persist on the dashboard.

Array of objects (DashboardContainer) <= 50 items

Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "API Monitoring Dashboard",
  • "tiles": [
    ],
  • "tags": [
    ],
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Dashboard

Retrieves a specific dashboard by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a567890

Dashboard ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Dashboard

Updates an existing dashboard.

Concurrency: This endpoint does not support optimistic concurrency control. Concurrent PUT requests for the same dashboard may silently overwrite each other, which can leave orphan tile-to-container references on layout-shape edits. Clients should serialize edits to a given dashboard.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a567890

Dashboard ID

Request Body schema: application/json
required
name
required
string <= 1024 characters

Dashboard name.

required
Array of objects (TileInput) <= 500 items

Full list of tiles for the dashboard. Existing tiles are matched by ID; tiles with an ID that does not match an existing tile will be assigned a new generated ID.

tags
Array of strings <= 50 items [ items <= 32 characters ]

Tags for organizing and filtering dashboards.

Array of objects (Filter)

Dashboard filter keys on the dashboard, applied across all tiles

savedQuery
string or null

Optional default dashboard query to persist on the dashboard.

savedQueryLanguage
string (QueryLanguage)
Enum: "sql" "lucene"

Query language for the where clause.

Array of objects (SavedFilterValue)

Optional default dashboard filter values to persist on the dashboard.

Array of objects (DashboardContainer) <= 50 items

Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Dashboard Name",
  • "tiles": [
    ],
  • "tags": [
    ],
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Dashboard

Deletes a dashboard

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a567890

Dashboard ID

Responses

Response samples

Content type
application/json
{ }

Alerts

Endpoints for managing monitoring alerts

Get Alert

Retrieves a specific alert by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a123456

Alert ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Alert

Updates an existing alert

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a123456

Alert ID

Request Body schema: application/json
required
dashboardId
string or null

Dashboard ID for tile-based alerts.

tileId
string or null

Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

savedSearchId
string or null

Saved search ID for saved_search alerts.

groupBy
string or null

Group-by key for saved search alerts.

threshold
required
number

Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.

thresholdMax
number or null

Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

interval
required
string (AlertInterval)
Enum: "1m" "5m" "15m" "30m" "1h" "6h" "12h" "1d"

Evaluation interval.

scheduleOffsetMinutes
integer or null >= 0

Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).

scheduleStartAt
string or null <date-time>

Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

source
string (AlertSource)
Enum: "saved_search" "tile"

Alert source type.

thresholdType
required
string (AlertThresholdType)
Enum: "above" "below" "above_exclusive" "below_or_equal" "equal" "not_equal" "between" "not_between"

Threshold comparison direction.

required
any (AlertChannel)
name
string or null

Human-friendly alert name.

message
string or null

Alert message template.

note
string or null [ 1 .. 4096 ] characters

Freeform note for the alert. Supports markdown formatting.

Responses

Request samples

Content type
application/json
{
  • "threshold": 500,
  • "interval": "1h",
  • "thresholdType": "above",
  • "source": "tile",
  • "dashboardId": "65f5e4a3b9e77c001a567890",
  • "tileId": "65f5e4a3b9e77c001a901234",
  • "channel": {
    },
  • "name": "Updated Alert Name",
  • "message": "Updated threshold and interval"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Alert

Deletes an alert

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 65f5e4a3b9e77c001a123456

Alert ID

Responses

Response samples

Content type
application/json
{ }

List Alerts

Retrieves a list of all alerts for the authenticated team

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create Alert

Creates a new alert

Authorizations:
BearerAuth
Request Body schema: application/json
required
dashboardId
string or null

Dashboard ID for tile-based alerts.

tileId
string or null

Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.

savedSearchId
string or null

Saved search ID for saved_search alerts.

groupBy
string or null

Group-by key for saved search alerts.

threshold
required
number

Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.

thresholdMax
number or null

Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.

interval
required
string (AlertInterval)
Enum: "1m" "5m" "15m" "30m" "1h" "6h" "12h" "1d"

Evaluation interval.

scheduleOffsetMinutes
integer or null >= 0

Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).

scheduleStartAt
string or null <date-time>

Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.

source
string (AlertSource)
Enum: "saved_search" "tile"

Alert source type.

thresholdType
required
string (AlertThresholdType)
Enum: "above" "below" "above_exclusive" "below_or_equal" "equal" "not_equal" "between" "not_between"

Threshold comparison direction.

required
any (AlertChannel)
name
string or null

Human-friendly alert name.

message
string or null

Alert message template.

note
string or null [ 1 .. 4096 ] characters

Freeform note for the alert. Supports markdown formatting.

Responses

Request samples

Content type
application/json
{
  • "dashboardId": "65f5e4a3b9e77c001a567890",
  • "tileId": "65f5e4a3b9e77c001a901234",
  • "threshold": 100,
  • "interval": "1h",
  • "source": "tile",
  • "thresholdType": "above",
  • "channel": {
    },
  • "name": "Error Spike Alert",
  • "message": "Error rate has exceeded 100 in the last hour"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Charts

Endpoints for querying chart data

Query Chart Series Data

Retrieves time series data based on configured series parameters

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
Array of objects (ChartSeries) [ 1 .. 5 ] items

Array of series configurations

startTime
required
number

Start timestamp in milliseconds

endTime
required
number

End timestamp in milliseconds

granularity
string
Enum: "30s" "1m" "5m" "10m" "15m" "30m" "1h" "2h" "6h" "12h" "1d" "2d" "7d" "30d" "auto"

Time bucket size for aggregations

seriesReturnType
string
Enum: "ratio" "column"

Format of the returned data

Responses

Request samples

Content type
application/json
Example
{
  • "startTime": 1647014400000,
  • "endTime": 1647100800000,
  • "granularity": "1h",
  • "series": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Sources

Endpoints for managing data sources

List Sources

Retrieves a list of all sources for the authenticated team

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Webhooks

Endpoints for managing webhooks

List Webhooks

Retrieves a list of all webhooks for the authenticated team

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{}

Search

Endpoints for querying raw data from log and trace sources

Search Raw Logs and Traces

Fetch individual log or trace rows from a HyperDX source.

This endpoint mirrors the "search" panel mode in the HyperDX UI. HyperDX applies the same query optimizations used in the UI:

  • Named attribute columns (e.g. "pipedream.pipeline_name") are rewritten to their indexed materialized equivalents when the source schema exposes them, avoiding slow Map lookups.
  • Rows are ordered by timestamp descending (most recent first).
  • The source's built-in PREWHERE / partition pruning is applied.

Authentication: Bearer token (personal API key from Team Settings).

Authorizations:
BearerAuth
Request Body schema: application/json
required
sourceId
required
string

Source ID to query. Call GET /api/v2/sources to list available sources. The source determines the underlying ClickHouse table (e.g. otel.otel_logs, otel.otel_traces) and its column schema.

startTime
string <date-time>

Start of the query window (ISO 8601). Defaults to 15 minutes before endTime. Must be before endTime.

endTime
string <date-time>

End of the query window (ISO 8601). Defaults to now.

where
string <= 8192 characters
Default: ""

Row filter expression. The language is controlled by whereLanguage.

Lucene examples (default): SeverityText:ERROR pipedream.pipeline_name:my-pipeline AND SeverityText:ERROR Body:timeout

SQL examples (whereLanguage: "sql"): SeverityText = 'ERROR' pipedream.pipeline_name = 'my-pipeline'

whereLanguage
string
Default: "lucene"
Enum: "lucene" "sql"

Language used for the where filter. Default is lucene.

select
string <= 4096 characters
Default: ""

Comma-separated list of ClickHouse column expressions to include in each result row. When omitted the source's default select expression is used.

Each entry is a ClickHouse SQL expression executed under the team's database user. Semicolons and subqueries (SELECT keyword) are rejected; use column references, map lookups, or function calls only.

HyperDX rewrites known attribute column names to their materialized equivalents automatically; you can still pass the logical name.

orderBy
string <= 1024 characters

ClickHouse ORDER BY expression. When omitted the source's default ordering (typically timestamp DESC) is used.

maxResults
integer [ 1 .. 2000 ]
Default: 100

Maximum number of rows to return. Default is 100, max is 2000.

offset
integer [ 0 .. 10000 ]
Default: 0

Number of rows to skip (best-effort offset pagination). Default is 0, max is 10000. Offset pagination is non-deterministic when multiple rows share the same timestamp; for reliable deep paging filter by the last Timestamp value returned in the previous page instead of using a large offset.

Responses

Request samples

Content type
application/json
Example
{
  • "sourceId": "69b46cb0d964ce2d0b9506a8",
  • "startTime": "2026-05-10T00:00:00Z",
  • "endTime": "2026-05-10T01:00:00Z",
  • "where": "SeverityText:ERROR",
  • "select": "Timestamp,SeverityText,Body,ServiceName",
  • "maxResults": 50
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "rows": 1
}