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
{ }

Validate Dashboard

Validates a dashboard body against the same schema and tile rules used by POST /api/v2/dashboards. The dashboard is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a dashboard configuration is valid before applying it.

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
{
  • "name": "New Dashboard",
  • "tiles": [
    ],
  • "tags": [
    ],
  • "filters": [
    ],
  • "savedQuery": "service.name = 'api'",
  • "savedQueryLanguage": "sql",
  • "savedFilterValues": [
    ],
  • "containers": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "valid": true,
  • "errors": [ ],
  • "normalized": {
    }
}

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": [
    ]
}

Connections

Endpoints for managing ClickHouse connections

List Connections

Retrieves a list of all ClickHouse connections for the authenticated team. Passwords are never returned.

Authorizations:
BearerAuth

Responses

Response samples

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

Create Connection

Creates a new ClickHouse connection

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

Display name for the connection.

host
required
string

ClickHouse HTTP endpoint URL.

username
required
string

ClickHouse username.

password
string

ClickHouse password. Never returned by the API.

hyperdxSettingPrefix
string or null

Optional prefix for HyperDX-specific ClickHouse settings. Must only contain alphanumeric characters and underscores.

isPrometheusEndpoint
boolean

Optional. When true, host is treated as a Prometheus-compatible API endpoint (e.g. Prometheus or Thanos) and PromQL queries are proxied to it. When false or omitted, host is a ClickHouse HTTP endpoint.

Responses

Request samples

Content type
application/json
{
  • "name": "Production ClickHouse",
  • "host": "https://clickhouse.example.com:8443",
  • "username": "default",
  • "password": "my-secret-password",
  • "hyperdxSettingPrefix": "hyperdx_",
  • "isPrometheusEndpoint": false
}

Response samples

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

Get Connection

Retrieves a specific ClickHouse connection by ID. Passwords are never returned.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439012

Connection ID

Responses

Response samples

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

Update Connection

Updates an existing ClickHouse connection.

Field semantics: if password is omitted or empty the existing password is kept. hyperdxSettingPrefix is cleared when set to null or an empty string, and prometheusEndpoint is cleared when set to null; both are kept unchanged when omitted.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439012

Connection ID

Request Body schema: application/json
required
name
required
string

Display name for the connection.

host
required
string

ClickHouse HTTP endpoint URL.

username
required
string

ClickHouse username.

password
string

ClickHouse password. If omitted or empty, the existing password is kept.

hyperdxSettingPrefix
string or null

Optional prefix for HyperDX-specific ClickHouse settings. Set to null or an empty string to clear the existing value. If omitted, the existing value is kept.

isPrometheusEndpoint
boolean

Optional. When true, host is treated as a Prometheus-compatible API endpoint. When false or omitted, host is a ClickHouse HTTP endpoint. Omit to keep the existing value unchanged.

Responses

Request samples

Content type
application/json
{
  • "name": "Production ClickHouse",
  • "host": "https://clickhouse.example.com:8443",
  • "username": "default",
  • "password": "my-new-secret-password",
  • "hyperdxSettingPrefix": "hyperdx_",
  • "isPrometheusEndpoint": false
}

Response samples

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

Delete Connection

Deletes a ClickHouse connection

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439012

Connection ID

Responses

Response samples

Content type
application/json
{ }

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
}

Team

Get Team

Retrieves the authenticated team's basic settings.

Authorizations:
BearerAuth

Responses

List Team Members

Retrieves the team's members.

Authorizations:
BearerAuth

Responses

Invite Team Member

Creates a pending invitation for a new email address.

Authorizations:
BearerAuth

Responses

List Team Invitations

Retrieves the team's pending invitations.

Authorizations:
BearerAuth

Responses

Delete Team Invitation

Deletes a pending team invitation.

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Remove Team Member

Removes a member from the team.

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses