Search Raw Logs and Traces

POST/api/v2/search

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

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Request bodyJSON

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

Example: "69b46cb0d964ce2d0b9506a8"
startTimeoptionalstring
Start of the query window (ISO 8601). Defaults to 15 minutes before endTime. Must be before endTime.

format: date-time
Example: "2026-05-10T00:00:00Z"
endTimeoptionalstring
End of the query window (ISO 8601). Defaults to now.

format: date-time
Example: "2026-05-10T01:00:00Z"
whereoptionalstring
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'

maxLength: 8192
Default: "" · Example: "SeverityText:ERROR"
whereLanguageoptionalluceneorsql
Language used for the where filter. Default is lucene.

Default: "lucene" · Example: "lucene"
selectoptionalstring
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.

maxLength: 4096
Default: "" · Example: "Timestamp,SeverityText,Body,pipedream.pipeline_name"
orderByoptionalstring
ClickHouse ORDER BY expression. When omitted the source's default ordering (typically timestamp DESC) is used.

maxLength: 1024
Example: "Timestamp DESC"
maxResultsoptionalinteger
Maximum number of rows to return. Default is 100, max is 2000.

maximum: 2000, minimum: 1
Default: 100
offsetoptionalinteger
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.

maximum: 10000, minimum: 0
Default: 0

Response

JSON

200

Matching rows returned successfully