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.

numConsecutiveWindows
integer or null >= 1

Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.

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 alerts for the authenticated team (paginated). Results are capped at limit (default and maximum 1000). When more records exist than are returned, meta.total exceeds data.length; clients with large collections must page with limit/offset to retrieve them all.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000

Maximum number of alerts to return.

offset
integer >= 0
Default: 0

Number of alerts to skip before returning results.

Responses

Response samples

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

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.

numConsecutiveWindows
integer or null >= 1

Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.

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",
  • "numConsecutiveWindows": 3
}

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

Create Source

Creates a new source.

The request body is a source object without the id field. If an id is sent anyway it is silently ignored (stripped before validation — the request is never rejected because of it). Granularity fields (materializedViews[].minGranularity and metadataMaterializedViews.granularity) accept the same short format the API returns (e.g. 5m, 15s, 1h, 1d).

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

Display name for the source.

section
string <= 256 characters

Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

disabled
boolean or null

When true, the source is hidden from source selectors in the UI. Defaults to false.

kind
required
string

Source kind discriminator. Must be "log" for log sources.

connection
required
string

ID of the ClickHouse connection used by this source.

required
object (SourceFrom)
Array of objects or null (QuerySetting)

Optional ClickHouse query settings applied when querying this source.

defaultTableSelectExpression
required
string

Default columns selected in search results (this can be customized per search later)

timestampValueExpression
required
string

DateTime column or expression that is part of your table's primary key.

serviceNameExpression
string or null

Expression to extract the service name from log rows.

severityTextExpression
string or null

Expression to extract the severity/log level text.

bodyExpression
string or null

Expression to extract the log message body.

eventAttributesExpression
string or null

Expression to extract event-level attributes.

resourceAttributesExpression
string or null

Expression to extract resource-level attributes.

displayedTimestampValueExpression
string or null

This DateTime column is used to display and order search results.

metricSourceId
string or null

HyperDX Source for metrics associated with logs. Optional

traceSourceId
string or null

HyperDX Source for traces associated with logs. Optional

traceIdExpression
string or null

Expression to extract the trace ID for correlating logs with traces.

spanIdExpression
string or null

Expression to extract the span ID for correlating logs with traces.

implicitColumnExpression
string or null

Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.

knownColumnsListExpression
string or null

For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.

useTextIndexForImplicitColumn
string or null
Enum: "auto" "enabled" "disabled"

Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.

Array of objects or null (HighlightedAttributeExpression)

Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.

Array of objects or null (HighlightedAttributeExpression)

Expressions defining row-level attributes which are displayed in the row side panel for the selected row.

Array of objects or null (MaterializedView)

Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.

object or null

Configure materialized views for fast field discovery and value autocomplete.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Logs",
  • "section": "Billing",
  • "disabled": false,
  • "kind": "log",
  • "connection": "507f1f77bcf86cd799439012",
  • "from": {
    },
  • "querySettings": [
    ],
  • "defaultTableSelectExpression": "Timestamp, ServiceName, SeverityText, Body",
  • "timestampValueExpression": "Timestamp",
  • "serviceNameExpression": "ServiceName",
  • "severityTextExpression": "SeverityText",
  • "bodyExpression": "Body",
  • "eventAttributesExpression": "LogAttributes",
  • "resourceAttributesExpression": "ResourceAttributes",
  • "displayedTimestampValueExpression": "TimestampTime",
  • "metricSourceId": "507f1f77bcf86cd799439013",
  • "traceSourceId": "507f1f77bcf86cd799439014",
  • "traceIdExpression": "TraceId",
  • "spanIdExpression": "SpanId",
  • "implicitColumnExpression": "Body",
  • "knownColumnsListExpression": "Timestamp, Body, ServiceName",
  • "useTextIndexForImplicitColumn": "auto",
  • "highlightedTraceAttributeExpressions": [
    ],
  • "highlightedRowAttributeExpressions": [
    ],
  • "materializedViews": [
    ],
  • "metadataMaterializedViews": {
    }
}

Response samples

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

Get Source

Retrieves a specific source by ID

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

Source ID

Responses

Response samples

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

Update Source

Updates an existing source. The full source object must be provided; this is a replace, not a patch.

The request body is a source object without the id field. If an id is sent anyway it is silently ignored (stripped before validation — never a 400); the path parameter alone identifies the source. Granularity fields (materializedViews[].minGranularity and metadataMaterializedViews.granularity) accept the same short format the API returns (e.g. 5m, 15s, 1h, 1d).

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

Source ID

Request Body schema: application/json
required
name
required
string

Display name for the source.

section
string <= 256 characters

Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.

disabled
boolean or null

When true, the source is hidden from source selectors in the UI. Defaults to false.

kind
required
string

Source kind discriminator. Must be "log" for log sources.

connection
required
string

ID of the ClickHouse connection used by this source.

required
object (SourceFrom)
Array of objects or null (QuerySetting)

Optional ClickHouse query settings applied when querying this source.

defaultTableSelectExpression
required
string

Default columns selected in search results (this can be customized per search later)

timestampValueExpression
required
string

DateTime column or expression that is part of your table's primary key.

serviceNameExpression
string or null

Expression to extract the service name from log rows.

severityTextExpression
string or null

Expression to extract the severity/log level text.

bodyExpression
string or null

Expression to extract the log message body.

eventAttributesExpression
string or null

Expression to extract event-level attributes.

resourceAttributesExpression
string or null

Expression to extract resource-level attributes.

displayedTimestampValueExpression
string or null

This DateTime column is used to display and order search results.

metricSourceId
string or null

HyperDX Source for metrics associated with logs. Optional

traceSourceId
string or null

HyperDX Source for traces associated with logs. Optional

traceIdExpression
string or null

Expression to extract the trace ID for correlating logs with traces.

spanIdExpression
string or null

Expression to extract the span ID for correlating logs with traces.

implicitColumnExpression
string or null

Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.

knownColumnsListExpression
string or null

For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.

useTextIndexForImplicitColumn
string or null
Enum: "auto" "enabled" "disabled"

Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.

Array of objects or null (HighlightedAttributeExpression)

Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.

Array of objects or null (HighlightedAttributeExpression)

Expressions defining row-level attributes which are displayed in the row side panel for the selected row.

Array of objects or null (MaterializedView)

Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.

object or null

Configure materialized views for fast field discovery and value autocomplete.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Logs",
  • "section": "Billing",
  • "disabled": false,
  • "kind": "log",
  • "connection": "507f1f77bcf86cd799439012",
  • "from": {
    },
  • "querySettings": [
    ],
  • "defaultTableSelectExpression": "Timestamp, ServiceName, SeverityText, Body",
  • "timestampValueExpression": "Timestamp",
  • "serviceNameExpression": "ServiceName",
  • "severityTextExpression": "SeverityText",
  • "bodyExpression": "Body",
  • "eventAttributesExpression": "LogAttributes",
  • "resourceAttributesExpression": "ResourceAttributes",
  • "displayedTimestampValueExpression": "TimestampTime",
  • "metricSourceId": "507f1f77bcf86cd799439013",
  • "traceSourceId": "507f1f77bcf86cd799439014",
  • "traceIdExpression": "TraceId",
  • "spanIdExpression": "SpanId",
  • "implicitColumnExpression": "Body",
  • "knownColumnsListExpression": "Timestamp, Body, ServiceName",
  • "useTextIndexForImplicitColumn": "auto",
  • "highlightedTraceAttributeExpressions": [
    ],
  • "highlightedRowAttributeExpressions": [
    ],
  • "materializedViews": [
    ],
  • "metadataMaterializedViews": {
    }
}

Response samples

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

Delete Source

Deletes a source

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

Source ID

Responses

Response samples

Content type
application/json
{ }

Webhooks

Endpoints for managing webhooks

List Webhooks

Retrieves webhooks for the authenticated team (paginated). Results are capped at limit (default and maximum 1000). When more records exist than are returned, meta.total exceeds data.length; clients with large collections must page with limit/offset to retrieve them all.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000

Maximum number of webhooks to return.

offset
integer >= 0
Default: 0

Number of webhooks to skip before returning results.

Responses

Response samples

Content type
application/json
{}

Create Webhook

Creates a new webhook for the authenticated team.

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

Webhook name. Must be unique per service within the team.

service
required
string
Enum: "slack" "incidentio" "generic"

Webhook service type.

url
required
string <uri> <= 2048 characters

Webhook destination URL.

description
string <= 2048 characters

Webhook description, shown in the UI.

body
string <= 16384 characters

Optional request body template. Only for generic/incidentio; rejected for slack.

object <= 100 properties

Write-only. Custom HTTP headers sent with the webhook request. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

object <= 100 properties

Write-only. Query parameters appended to the webhook URL. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Update Webhook

Replaces an existing webhook. Readable optional fields (description, body) are a full replace: omitting them clears them. The write-only fields headers and queryParams are never returned on read, so omitting them preserves the stored values; send an explicit empty object ({}) to clear them. Exception: if the destination (url or service) changes, omitted headers/ queryParams are cleared rather than preserved so stored secrets are never forwarded to a new destination.

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

Webhook ID

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

Webhook name. Must be unique per service within the team.

service
required
string
Enum: "slack" "incidentio" "generic"

Webhook service type.

url
required
string <uri> <= 2048 characters

Webhook destination URL.

description
string <= 2048 characters

Webhook description, shown in the UI.

body
string <= 16384 characters

Optional request body template. Only for generic/incidentio; rejected for slack.

object <= 100 properties

Write-only. Custom HTTP headers sent with the webhook request. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

object <= 100 properties

Write-only. Query parameters appended to the webhook URL. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete Webhook

Deletes a webhook. Blocked with a 409 while any alert still references it — reassign or remove those alerts first — so deletion never leaves an alert pointing at a missing webhook (which would silently drop notifications). Mirrors the internal webhook delete guard.

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

Webhook ID

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
}

Saved Searches

List Saved Searches

Retrieves saved searches for the authenticated team (paginated). Results are capped at limit (default and maximum 1000). When more records exist than are returned, meta.total exceeds data.length; clients with large collections must page with limit/offset to retrieve them all.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 1000

Maximum number of saved searches to return.

offset
integer >= 0
Default: 0

Number of saved searches to skip before returning results.

Responses

Response samples

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

Create Saved Search

Creates a new saved search.

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

Display name for the saved search.

sourceId
required
string

ID of the source to query. Must belong to the team.

select
string <= 4096 characters

Comma-separated list of column expressions to display. Empty uses the source default.

where
string <= 8192 characters

Row filter expression. The language is controlled by whereLanguage.

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

Language used for the where filter.

orderBy
string <= 1024 characters

ORDER BY expression. Empty uses the source default.

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

Tags used to organize saved searches.

Array of objects (SavedSearchFilter) <= 100 items

Structured pinned filters applied to the search.

Responses

Request samples

Content type
application/json
{
  • "name": "Production Errors",
  • "sourceId": "507f1f77bcf86cd799439012",
  • "select": "Timestamp, ServiceName, Body",
  • "where": "SeverityText:ERROR",
  • "whereLanguage": "lucene",
  • "orderBy": "Timestamp DESC",
  • "tags": [
    ],
  • "filters": [
    ]
}

Response samples

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

Get Saved Search

Retrieves a specific saved search by ID.

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

Saved search ID

Responses

Response samples

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

Update Saved Search

Updates an existing saved search. This is a full replace: send the full object. Every optional field (select, where, whereLanguage, orderBy, tags, filters) is always written and falls back to its default when omitted, so omitting a field resets it rather than preserving the stored value.

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

Saved search ID

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

Display name for the saved search.

sourceId
required
string

ID of the source to query. Must belong to the team.

select
string <= 4096 characters

Comma-separated list of column expressions to display. Empty uses the source default.

where
string <= 8192 characters

Row filter expression. The language is controlled by whereLanguage.

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

Language used for the where filter.

orderBy
string <= 1024 characters

ORDER BY expression. Empty uses the source default.

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

Tags used to organize saved searches.

Array of objects (SavedSearchFilter) <= 100 items

Structured pinned filters applied to the search.

Responses

Request samples

Content type
application/json
{
  • "name": "Production Errors",
  • "sourceId": "507f1f77bcf86cd799439012",
  • "select": "Timestamp, ServiceName, Body",
  • "where": "SeverityText:ERROR",
  • "whereLanguage": "lucene",
  • "orderBy": "Timestamp DESC",
  • "tags": [
    ],
  • "filters": [
    ]
}

Response samples

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

Delete Saved Search

Deletes a saved search and any alerts attached to it.

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

Saved search ID

Responses

Response samples

Content type
application/json
{ }

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