# Retrieve chunks (/docs/api/retrieve)
<EndpointLayout>
<EndpointHeader method="POST" path="/v1/engine/retrieve" />

Searches the engine's vector and OKF sources, ranks what it finds, and returns the chunks for your own model to use. `lynk.retrieve` calls it for you.

<EndpointExamples>
<CodeTabs>
  <Tab value="cURL">
    ```bash
    curl https://api.docklee.com/v1/engine/retrieve \
      -H "Authorization: Bearer $DOCKLEE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"engine_id": "your-engine-id", "query": "What is the refund window?", "top_k": 5}'
    ```
  </Tab>
  <Tab value="Python">
    ```python
    from docklee import Lynk

    lynk = Lynk(engine_id="your-engine-id")
    chunks = lynk.retrieve_sync("What is the refund window?", top_k=5)
    ```
  </Tab>
  <Tab value="TypeScript">
    ```ts
    import { Lynk } from 'docklee';

    const lynk = new Lynk({ engineId: 'your-engine-id' });
    const chunks = await lynk.retrieve('What is the refund window?', { topK: 5 });
    ```
  </Tab>
</CodeTabs>

<Tabs items={['200']}>
  <Tab value="200">
    ```json
    {
      "chunks": [
        {
          "chunk_id": "c2a8f5e1-7b39-4d6c-a014-8e3f2b9d61c7",
          "content": "Customers can request a refund within 30 days of purchase.",
          "metadata": {"policy": "refunds"}
        },
        {
          "chunk_id": "7e3b9a04-1f6c-4d25-8b97-2a5e0c8d1f63",
          "content": "After 30 days, purchases can be exchanged for store credit.",
          "metadata": {"policy": "refunds"}
        }
      ]
    }
    ```
  </Tab>
</Tabs>
</EndpointExamples>

## Body [#body]

<ApiFields>
  <ApiField name="engine_id" type="string<uuid>" required>
    The engine to search.
  </ApiField>
  <ApiField name="query" type="string" required>
    The question, in plain words.
  </ApiField>
  <ApiField name="top_k" type="integer" defaultValue="8">
    How many chunks to return, from 1 to 100. Your plan can cap it lower.
  </ApiField>
</ApiFields>

## Response [#response]

<ApiFields>
  <ApiField name="chunks" type="object[]" required>
    The chunks, best match first.
  </ApiField>
  <ApiField name="chunks[].chunk_id" type="string<uuid>" required>
    The chunk's ID. Matches `chunk_id` in query citations.
  </ApiField>
  <ApiField name="chunks[].content" type="string" required>
    The chunk's text.
  </ApiField>
  <ApiField name="chunks[].metadata" type="object" required>
    The metadata stored with the chunk.
  </ApiField>
</ApiFields>

## Status codes [#status-codes]

| Status | Meaning |
| --- | --- |
| `200` | The search ran. An empty list means nothing matched. |
| `401` | The key is missing, malformed, or revoked. |
| `402` | Your plan's monthly allowance is used up. |
| `403` | The key's capability or scope doesn't allow reading this engine. |
| `404` | The engine doesn't exist in the key's workspace. |
| `422` | A field is missing or invalid. |
| `429` | The read rate limit was hit. |
</EndpointLayout>
