query

Search one or more sources over an absolute time window.

Input:

{
  "source_ids": ["app_logs", "workflow_metrics"],
  "start_time": "2026-04-02T12:00:00Z",
  "end_time": "2026-04-02T12:15:00Z",
  "text": "SERVICE_RELOAD",
  "filters": [
    { "field": "region", "value": "us-east-1" },
    { "field": "traceId", "value": "trace-12345" }
  ],
  "nested_filters": [
    {
      "path": "steps",
      "field": "name",
      "value": "CACHE_REFRESH"
    }
  ],
  "extract_nested": true,
  "mode": "hits",
  "sort_by": "total_duration_ms",
  "sort": "desc",
  "limit": 50
}

Modes

Mode	Required fields	Optional fields
hits		sort_by (sort on a chosen field)
count
histogram	histogram_interval
terms	group_by
stats	stats_field	group_by
grouped_top_hits	group_by, sort_by	top_hits_size

Field resolution

• Exact filters and grouped bucket fields use field-hint aliases and, with metadata, schema-aware exact-field preference.
• Rewriting event to safer exact field event.keyword returns an advisory.
• Without metadata, queries use the requested field and return schema_unavailable; exact-safe resolution is not claimed.
• Nested filters require working schema metadata; otherwise they fail early with a configuration error, not a backend 404.

Every response includes query_echo: sources, bounds, filters and mode actually used.

Cursor pagination

For large hit sets, pass cursor. Supported only for single-source hits queries:

{
  "source_ids": ["workflow_metrics"],
  "start_time": "2026-04-02T12:00:00Z",
  "end_time": "2026-04-02T12:15:00Z",
  "mode": "hits",
  "limit": 100,
  "cursor": "REPLACE_ME_NEXT_CURSOR"
}

stats example

{
  "source_ids": ["workflow_metrics"],
  "start_time": "2026-04-02T12:00:00Z",
  "end_time": "2026-04-02T12:15:00Z",
  "mode": "stats",
  "stats_field": "total_duration_ms",
  "group_by": "trace_id",
  "limit": 25
}

grouped_top_hits example

{
  "source_ids": ["workflow_metrics"],
  "start_time": "2026-04-02T12:00:00Z",
  "end_time": "2026-04-02T12:15:00Z",
  "mode": "grouped_top_hits",
  "group_by": "trace_id",
  "sort_by": "total_duration_ms",
  "top_hits_size": 1,
  "limit": 25
}