Sign in

v1

latestOpenAPI 3.0.02026-07-1738124256.1 KB
Search

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).

post/api/v2/search

Request body

sourceIdstring required

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.

startTimestring date-time

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

endTimestring date-time

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

wherestring

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'lucene' | 'sql'

Language used for the where filter. Default is lucene.

selectstring

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.

orderBystring

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

maxResultsinteger

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

offsetinteger

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.

Example request

{
  "sourceId": "69b46cb0d964ce2d0b9506a8",
  "startTime": "2026-05-10T00:00:00Z",
  "endTime": "2026-05-10T01:00:00Z",
  "where": "SeverityText:ERROR",
  "whereLanguage": "lucene",
  "select": "Timestamp,SeverityText,Body,pipedream.pipeline_name",
  "orderBy": "Timestamp DESC"
}

Response

Matching rows returned successfully

dataSearchRow[]

Array of result rows. Each row is an object with keys corresponding to the requested columns.

rowsinteger

Number of rows in this response (not total matching rows).