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

Error

recentErrors

A valid request URL is required to generate request examples

200

{
  "data": [
    {
      "Timestamp": "2026-05-10T00:01:23.456789000Z",
      "SeverityText": "ERROR",
      "Body": "connection refused: redis:6379",
      "ServiceName": "api-service"
    }
  ],
  "rows": 1
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

sourceId · string · 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.

Example:

"69b46cb0d964ce2d0b9506a8"

startTime · string<date-time>

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

Example:

"2026-05-10T00:00:00Z"

endTime · string<date-time>

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

Example:

"2026-05-10T01:00:00Z"

where · string · 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'

Maximum string length: 8192

Example:

"SeverityText:ERROR"

whereLanguage · enum<string> · default: lucene

Language used for the where filter. Default is lucene.

Available options: lucene, sql

Example:

"lucene"

select · string · 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.

Maximum string length: 4096

Example:

"Timestamp,SeverityText,Body,pipedream.pipeline_name"

orderBy · string

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

Maximum string length: 1024

Example:

"Timestamp DESC"

maxResults · integer · default: 100

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

Required range: 1 <= x <= 2000

offset · integer · 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.

Required range: 0 <= x <= 10000

Response

200

application/json

Matching rows returned successfully

data · object[]

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

rows · integer

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