---
title: "Search a data lake"
method: POST
path: "/api/v1/data-lakes/{id}/search"
tags: ["Data Lakes"]
---

# Search a data lake

`POST /api/v1/data-lakes/{id}/search`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/data-lakes/{id}/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Semantic (vector) search over one lake: the query is embedded with the model the corpus was indexed with and the top `top_k` passages at or above `min_score` are returned. Only members of this lake are searched - never the caller's other files. `tags` narrows to files carrying any of the listed tags. Files still being indexed or paused are withheld rather than searched stale: `partial_results` is then true and `retrieval_unavailable` counts them (poll `GET /api/v1/data-lakes/{id}/files/{file_id}` for a specific file). The query embedding is billed as credits. Limited to 10 searches per minute per caller, shared with the product UI.

## Path parameters

- `id` string, required

## Request body

- SearchDataLakeRequest
  - `query` string, required
  - `top_k` integer
  - `min_score` number
  - `tags` string[]

## Response `200`

The ranked passages and what, if anything, was withheld.

- SearchDataLakeResponse200
  - `results` object[], required
    - `chunk_id` string, required
    - `file_id` string, required
    - `file_name` string, required
    - `chunk_text` string, required
    - `score` number, required
  - `embedding_model` string, required
  - `partial_results` boolean, required
  - `retrieval_unavailable` object, required
    - `indexing_files` integer, required
    - `paused_files` integer, required

## Other responses

- `400`: The API key bills an organization that no longer exists, or one its owner is no longer a member of.
- `401`: Missing or invalid credentials.
- `403`: The API key lacks `datalake:query`, or Data Lakes are disabled on this deployment.
- `404`: No lake with that id or slug is visible to the caller. A lake that exists but is not yours to read is reported as 404 too, so lake ids cannot be probed through this endpoint. A lake the caller can read but is not entitled to search is reported the same way, as is a lake that is not `active` yet (a draft lake is readable but not yet searchable).
- `405`: The path does not serve this HTTP method.
- `422`: Request body failed validation, or the caller cannot afford the query embedding - the latter is tagged `errorCode: "insufficient_credits"` (the balance is short, or the org member credit cap is exhausted).
- `429`: Search rate limit (10 per minute) or per-user API rate limit exceeded.
- `503`: No usable key is configured on this deployment for the embedding provider the query needs (`errorCode: "provider_not_configured"`).

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/0de0bdb0d113?raw)