> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/search-v3-and-streaming.md).

# Search Responses and Streaming

Query logs, traces, and Kubernetes events with wrapped responses and stream log and trace results.

Use the search endpoints below when you need numeric-column hints alongside query results. Logs and traces also support progressive results over Server-Sent Events (SSE).

### Endpoints

| Signal            | Method | Endpoint                    | Response             |
| ----------------- | ------ | --------------------------- | -------------------- |
| Logs              | POST   | `/api/logs/v3/search`       | JSON envelope or SSE |
| Traces            | POST   | `/api/traces/v3/search`     | JSON envelope or SSE |
| Kubernetes events | POST   | `/api/k8s/v3/events/search` | JSON envelope        |

The existing `/api/logs/v2/search`, `/api/traces/v2/search`, and `/api/k8s/v2/events/search` endpoints return a bare row array. Changing to a v3 path requires reading rows from `data` instead. The URL version does not select a different gcQL language. No `X-API-Version` header is required.

### Authentication

Send `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>`. JSON requests also require `Content-Type: application/json`. The examples use `https://api.groundcover.com`; use your deployment's API URL for a self-hosted installation. Replace the example time range with one containing your data.

### Request Body

| Field          | Type    | Required               | Description                                                   |
| -------------- | ------- | ---------------------- | ------------------------------------------------------------- |
| `start`        | string  | Yes                    | Start timestamp in RFC3339 format.                            |
| `end`          | string  | Yes                    | End timestamp in RFC3339 format; must not precede `start`.    |
| `query`        | string  | Yes for these examples | gcQL filter and pipeline.                                     |
| `enableStream` | boolean | No                     | Logs/traces only. Defaults to `false`; set to `true` for SSE. |

Use [gcQL pagination](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql.md#pagination) to retrieve additional rows. These endpoints return results on the request connection; they do not return a job ID or require a polling endpoint.

### Query Logs

```bash
curl --request POST 'https://api.groundcover.com/api/logs/v3/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "query": "level:error | stats by (workload) count() as errors | sort by (errors desc) | limit 10"
}'
```

An illustrative response is:

```json
{
  "data": [{"workload": "checkout-service", "errors": 12}],
  "valueFieldHints": ["errors"]
}
```

`data` contains the query-dependent rows. `valueFieldHints` identifies numeric result columns, including numeric aggregation columns whose values are null. It is a hint for choosing chart values, not a fixed schema.

For traces or events, use the corresponding endpoint with a query from [Query Traces](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql/query-traces.md) or [Query Kubernetes Events](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql/query-events.md).

### Stream Results

```bash
curl -N --request POST 'https://api.groundcover.com/api/logs/v3/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "query": "level:error | stats by (workload) count() as errors | limit 10",
  "enableStream": true
}'
```

`curl -N` disables output buffering. Parse the response as SSE, with JSON inside each `data:` field. Log event names are `logs_search`; trace event names are `traces_search`.

```
event: logs_search
data: {"done":false,"data":[{"workload":"checkout-service","errors":10}],"valueFieldHints":["errors"],"estimate":true}

event: logs_search
data: {"done":true,"data":[{"workload":"checkout-service","errors":12}],"valueFieldHints":["errors"],"estimate":false}
```

Each event is the latest result snapshot: replace the previous snapshot rather than concatenating rows or summing counts. `estimate` indicates estimated results; `done` marks completion. An error after streaming starts is reported as a terminal event with `done: true` and an `error` string, so HTTP status alone is insufficient to determine success. A connection that ends without a terminal event should be treated as incomplete. To stop receiving a stream, close the HTTP connection.

Kubernetes event search does not expose the streaming option. Streaming time-series queries use the separate [time-series endpoints](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md).

### Correlate Signals in One Query

Cross-domain gcQL subqueries also work through the API. For example, find log counts for sessions that recorded a RUM `TypeError`:

```bash
curl --request POST 'https://api.groundcover.com/api/logs/v3/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2026-10-28T10:00:00Z",
    "end": "2026-10-28T11:00:00Z",
    "query": "session_id:in(_from rum_events | error_type:TypeError | fields session_id) | stats by (session_id) count() as log_count | sort by (session_id asc) | limit 20"
  }'
```

This requires collected RUM events and a matching `session_id` on the logs. The subquery inherits the request time window. Specify any required signal-specific scope inside the subquery as well; do not assume an outer log filter is automatically applied to another signal. Results use the same `data` and `valueFieldHints` envelope.

For current infrastructure state, a subquery such as `pod:in(_from entities | kind:Pod status_phase:Running | fields name)` selects logs whose pod name appears among running Pods. Narrow both sides to the relevant cluster and namespace when names are not unique. See [Query Infrastructure Entities](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-entities.md) and [Query RUM](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-rum.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/search-v3-and-streaming.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
