---
title: "Search Raw Logs and Traces"
method: POST
path: "/api/v2/search"
tags: ["Search"]
---

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

## Request body

- SearchRequest
  - `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.
  - `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 — 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.
  - `select` string — 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 — ClickHouse ORDER BY expression. When omitted the source's default ordering (typically timestamp DESC) is used.
  - `maxResults` integer — Maximum number of rows to return. Default is 100, max is 2000.
  - `offset` integer — 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.

## Response `200`

Matching rows returned successfully

- SearchResponse
  - `data` SearchRow[] — 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).

## Other responses

- `400` — Invalid request parameters or query error
- `401` — Missing or invalid API key
- `404` — Source or connection not found
- `500` — Server error

## Changes

- **2026-05-19** `cec066aa8c43` — 1 info
  - endpoint added
- **2026-01-30** `ed852374c451` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/changes/api/v2/search/post.md)

---

[API](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api.md) · [All operations](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperdxio/hyperdx-external-api/revisions/d402e7286cf2/schema)