> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/v1/interfaces/apis/core-apis/api-reference/logs-search.md).

# Log search

Search logs for a specific tenant resource. The gateway proxies the request to the Logsearch upstream. Available as **v1** and **v2**. They use the same path parameters, query parameters, and headers. **The response shape differs**: v1 groups log entries by pod/container, while v2 returns a flat list with repeated metadata.

## Search logs (v1)

`GET` `/v1/tenants/{tenant}/resources/{type}/{version}/{name}/logs/search`

Upstream: Logsearch

### Path Parameters

<table><thead><tr><th width="137.524169921875">Name</th><th width="136.20068359375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>tenant</code></td><td>string</td><td>Tenant identifier, e.g. <code>engineering</code></td></tr><tr><td><code>type</code></td><td>string</td><td>Resource type, e.g. <code>service</code></td></tr><tr><td><code>version</code></td><td>string</td><td>Resource version, e.g. <code>v2alpha</code></td></tr><tr><td><code>name</code></td><td>string</td><td>Resource name, e.g. <code>dataproduct-mcp</code></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="168.124267578125">Name</th><th width="113.1383056640625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>q</code></td><td>string</td><td>Required. Log search query (e.g. <code>*</code> for all logs, or a keyword/phrase)</td></tr><tr><td><code>window</code></td><td>string</td><td>Relative time window, default <code>1h</code> (e.g. <code>1h</code>, <code>24h</code>). Use <strong>either</strong> <code>window</code> <strong>or</strong> <code>start_timestamp</code> + <code>end_timestamp</code>, not both</td></tr><tr><td><code>start_timestamp</code></td><td>number</td><td>Start of time range (Unix epoch seconds). Must be used with <code>end_timestamp</code></td></tr><tr><td><code>end_timestamp</code></td><td>number</td><td>End of time range (Unix epoch seconds). Must be used with <code>start_timestamp</code></td></tr><tr><td><code>limit</code></td><td>number</td><td>Maximum number of log hits to return, default <code>100</code> (1–1000)</td></tr><tr><td><code>offset</code></td><td>number</td><td>Pagination offset, default <code>0</code></td></tr><tr><td><code>run_id</code></td><td>string</td><td>Filter by run ID</td></tr><tr><td><code>cgroup</code></td><td>string</td><td>Filter by container group / pod name (e.g. <code>servicev2alphasvcwithinlinedisk01-gukd-0</code>)</td></tr><tr><td><code>container</code></td><td>string</td><td>Filter by container name</td></tr><tr><td><code>stream</code></td><td>string</td><td>Filter by log stream (<code>stdout</code> or <code>stderr</code>). May be passed empty</td></tr></tbody></table>

### Headers

<table><thead><tr><th width="225.6763916015625">Name</th><th>Value</th></tr></thead><tbody><tr><td><code>Authorization</code> or <code>apikey</code></td><td><code>Bearer &#x3C;access_token></code> or <code>&#x3C;your-apikey></code>. Required when gateway auth is enabled. See <a href="/pages/dDkusShTSZhYHkMmHOt1">Authentication</a></td></tr><tr><td><code>Accept</code></td><td><code>application/json</code> (recommended)</td></tr><tr><td><code>Dataos-Correlation-Id</code></td><td>Optional tracing ID</td></tr></tbody></table>

**cURL:**

{% code title="Basic search (all logs, last 24 hours)" expandable="true" collapsedlinecount="5" %}

```bash
curl -X GET \
  "https://$BASE_URL/v1/tenants/engineering/resources/service/v2alpha/dataproduct-mcp/logs/search?q=*&window=24h" \
  -H "Accept: application/json" \
  -H "apikey: <your-apikey>"
```

{% endcode %}

{% code title="Time window, stream, and cgroup filters" expandable="true" collapsedlinecount="5" %}

```bash
curl -X GET \
  "https://$BASE_URL/v1/tenants/engineering/resources/service/v2alpha/dataproduct-mcp/logs/search?q=*&window=1h&stream=&cgroup=servicev2alphasvcwithinlinedisk01-gukd-0" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access_token>"
```

{% endcode %}

{% code title="Pagination" expandable="true" collapsedlinecount="5" %}

```bash
curl -X GET \
  "https://$BASE_URL/v1/tenants/engineering/resources/service/v2alpha/dataproduct-mcp/logs/search?q=error&window=24h&limit=100&offset=0" \
  -H "Accept: application/json" \
  -H "apikey: <your-apikey>"
```

{% endcode %}

### Response

{% tabs %}
{% tab title="200" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 200,
  "data": {
    "total_hits": 1133,
    "offset": 0,
    "limit": 100,
    "results": {
      "servicev2alphadataproductmcp-89g9-5cc7577997-xw78p/dtprdctmcp": {
        "name": "servicev2alphadataproductmcp-89g9-5cc7577997-xw78p",
        "namespace": "intribeiks-0-engineering-0-ets",
        "dataplane": "ingressdp01",
        "containerName": "dtprdctmcp",
        "source": "quickwit",
        "logs": [
          { "time": "2026-07-27T23:01:30.671116Z", "stream": "stderr", "message": "..." }
        ]
      }
    }
  }
}
```

{% endcode %}

`data.results` is a map keyed by `<pod>/<container>`. Each entry has `name`, `namespace`, `dataplane`, `containerName`, `source`, and a `logs[]` array of `{time, stream, message}`. Multiple pods/containers may appear, each under its own key.
{% endtab %}

{% tab title="400" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 400,
  "error": { "code": "...", "message": "..." }
}
```

{% endcode %}

Missing or invalid query (e.g. missing `q`).
{% endtab %}

{% tab title="401" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 401,
  "error": { "code": "COMMON.AUTH.UNAUTHORIZED", "message": "..." }
}
```

{% endcode %}

Missing or invalid auth.
{% endtab %}

{% tab title="403" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 403,
  "error": { "code": "COMMON.AUTH.FORBIDDEN", "message": "..." }
}
```

{% endcode %}

Valid token but access denied.
{% endtab %}

{% tab title="500" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 500,
  "error": { "code": "...", "message": "..." }
}
```

{% endcode %}

Upstream or internal error.
{% endtab %}

{% tab title="502" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 502,
  "error": { "code": "COMMON.PROXY.UPSTREAM_ERROR", "message": "..." }
}
```

{% endcode %}

Logsearch upstream failure.
{% endtab %}
{% endtabs %}

## Search logs (v2)

`GET` `/v2/tenants/{tenant}/resources/{type}/{version}/{name}/logs/search`

Same path parameters, query parameters, and headers as v1 above. **The response is flattened**: `data.results` is an array of individual log entries, not a map of pod/container groups. Each entry includes `name`, `namespace`, `dataplane`, `containerName`, `source`, `time`, `stream`, and `message`. There is no nested `logs[]` array.

**cURL:**

{% code title="Basic search (v2)" expandable="true" collapsedlinecount="5" %}

```bash
curl -X GET \
  "https://$BASE_URL/v2/tenants/engineering/resources/service/v2alpha/dataproduct-mcp/logs/search?q=*&window=24h" \
  -H "Accept: application/json" \
  -H "apikey: <your-apikey>"
```

{% endcode %}

### Response

{% tabs %}
{% tab title="200" %}
Captured live from `GET /v2/tenants/stg/resources/app/v1alpha/orders-channel-performance-dashboard/logs/search?q=*&window=720h&limit=5`:

{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 200,
  "data": {
    "total_hits": 93,
    "offset": 0,
    "limit": 5,
    "results": [
      {
        "name": "srvcv1lphrdrschnnlprfrmncdshbrdsvc-09yz-54c74cf5cb-88bs6",
        "namespace": "productsandbox-0-stg-0-ets",
        "dataplane": "productazdp",
        "containerName": "rdrschnnlprfrmncdshbrdsvc",
        "source": "quickwit",
        "time": "2026-07-22T10:04:53.919421Z",
        "stream": "stdout",
        "message": ""
      },
      {
        "name": "srvcv1lphrdrschnnlprfrmncdshbrdsvc-09yz-54c74cf5cb-88bs6",
        "namespace": "productsandbox-0-stg-0-ets",
        "dataplane": "productazdp",
        "containerName": "rdrschnnlprfrmncdshbrdsvc",
        "source": "quickwit",
        "time": "2026-07-22T10:04:53.919460Z",
        "stream": "stdout",
        "message": "Collecting usage statistics. To deactivate, set browser.gatherUsageStats to false."
      },
      {
        "name": "srvcv1lphrdrschnnlprfrmncdshbrdsvc-09yz-54c74cf5cb-88bs6",
        "namespace": "productsandbox-0-stg-0-ets",
        "dataplane": "productazdp",
        "containerName": "rdrschnnlprfrmncdshbrdsvc",
        "source": "quickwit",
        "time": "2026-07-22T10:04:54.053010Z",
        "stream": "stderr",
        "message": "2026-07-22 10:04:54.052 Uvicorn server started on 0.0.0.0:8501"
      }
    ]
  }
}
```

{% endcode %}

`data.results` is a flat array. Each element is one log line with inlined pod/container metadata: `name`, `namespace`, `dataplane`, `containerName`, and `source`. Those values repeat across every log line from that pod. Compare this with v1's grouped shape above.
{% endtab %}

{% tab title="400" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 400,
  "error": { "code": "...", "message": "..." }
}
```

{% endcode %}

Missing or invalid query (e.g. missing `q`).
{% endtab %}

{% tab title="401" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 401,
  "error": { "code": "COMMON.AUTH.UNAUTHORIZED", "message": "..." }
}
```

{% endcode %}

Missing or invalid auth.
{% endtab %}

{% tab title="403" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 403,
  "error": { "code": "COMMON.AUTH.FORBIDDEN", "message": "..." }
}
```

{% endcode %}

Valid token but access denied.
{% endtab %}

{% tab title="500" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 500,
  "error": { "code": "...", "message": "..." }
}
```

{% endcode %}

Upstream or internal error.
{% endtab %}

{% tab title="502" %}
{% code expandable="true" collapsedlinecount="5" %}

```json
{
  "status": 502,
  "error": { "code": "COMMON.PROXY.UPSTREAM_ERROR", "message": "..." }
}
```

{% endcode %}

Logsearch upstream failure.
{% endtab %}
{% endtabs %}

## v1 vs v2

<table><thead><tr><th width="159.8248291015625"></th><th>v1</th><th>v2</th></tr></thead><tbody><tr><td>Path</td><td><code>$BASE_URL/v1/tenants/.../logs/search</code></td><td><code>$BASE_URL/v2/tenants/.../logs/search</code></td></tr><tr><td>Path/query params</td><td>Same</td><td>Same</td></tr><tr><td>Response shape</td><td><code>data.results</code> grouped by pod/container (map), each with a nested <code>logs[]</code></td><td><code>data.results</code> flat array, pod/container metadata inlined on every log entry</td></tr><tr><td>Upstream target</td><td>Logsearch <code>/api/v1/.../logs/search</code></td><td>Logsearch <code>/api/v2/.../logs/search</code></td></tr></tbody></table>

Use v1 if you want logs pre-grouped by pod/container. Use v2 if you want a flat, iterable list of log lines and would rather not write grouping logic yourself. `platform-api` forwards path and query params to the corresponding upstream API version either way.

## Notes

* `q` is **required**. Use `*` to match all log lines in the time window.
* Use `window` for relative ranges (`1h`, `24h`) or `start_timestamp` + `end_timestamp` for absolute ranges, not both.
* v1 groups results by pod/container under `data.results`, each with a `logs[]` array. v2 flattens the same data into one array under `data.results`, with pod/container fields repeated per entry.
* Default `limit` is `100`; increase up to `1000` and paginate with `offset`.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/v1/interfaces/apis/core-apis/api-reference/logs-search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.