> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve

> Two-stage codebase retrieval using semantic search

## Path Parameters

<ParamField path="repo_id" type="string" required>
  UUID of the target repo to retrieve over.

  <Warning>
    Target repo must be created with `auto_index: true` for semantic retrieval to work.
  </Warning>
</ParamField>

## Request Body

<ParamField body="query" type="string" required>
  Natural language description of what you're looking for
</ParamField>

<ParamField body="branch" type="string">
  Branch name to retrieve from. Returns results from the most recently indexed commit on the branch. Uses the default branch if neither `branch` nor `hash` is specified.

  <Note>
    Updated indices may not be available immediately after an edit/push. If you require results to reflect a recent change, use the `hash` parameter with the branch HEAD.
  </Note>
</ParamField>

<ParamField body="hash" type="string">
  Specific commit hash to retrieve from. Returns `404` if the commit has not been indexed. In cases where you are retrieving over a recently pushed commit, retry on `404` errors with an exponential backoff.

  <Note>
    Only "leaf" commits are indexed. Passing a commit that has never been a branch HEAD will permanently return `404`.
  </Note>
</ParamField>

<ParamField body="score_threshold" type="number" default={0.3}>
  Minimum relevance score for results (0.0 to 1.0)
</ParamField>

<ParamField body="token_limit" type="integer" default={30000}>
  Maximum number of tokens to return across all results
</ParamField>

<ParamField body="include_content" type="boolean" default={false}>
  Whether to include file content in the response. If false, only filenames and scores are returned.
</ParamField>

## Response

<ResponseField name="results" type="array">
  Array of relevant files and code sections

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="filename" type="string">
      Path to the file within the repo
    </ResponseField>

    <ResponseField name="score" type="number">
      Relevance score between 0.0 and 1.0
    </ResponseField>

    <ResponseField name="content" type="string">
      File content (only included when include\_content=true)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hash" type="string">
  Commit hash that was retrieved over
</ResponseField>

<ResponseField name="pending_embeddings" type="integer">
  Number of embeddings currently in progress

  <Warning>
    Query time may be slower and results may be degraded when there is a large number of pending embeddings.
  </Warning>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.relace.run/v1/repo/123e4567-e89b-12d3-a456-426614174000/retrieve \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "authentication and user login functionality",
      "branch": "main",
      "score_threshold": 0.3,
      "token_limit": 30000,
      "include_content": true
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  import { Relace } from "@relace-ai/relace";

  const client = new Relace({ apiKey: "YOUR_API_KEY" });

  const repoId = "123e4567-e89b-12d3-a456-426614174000";
  const result = await client.repo.retrieve(repoId, {
      query: "authentication and user login functionality",
      branch: "main",
      score_threshold: 0.3,
      token_limit: 30000,
      include_content: true
  });
  console.log(result);
  ```

  ```python Python SDK theme={null}
  from relace import Relace

  client = Relace(api_key="YOUR_API_KEY")

  repo_id = "123e4567-e89b-12d3-a456-426614174000"

  result = client.repo.retrieve(
      repo_id,
      query="authentication and user login functionality",
      branch="main",
      score_threshold=0.3,
      token_limit=30000,
      include_content=True,
  )

  print(result)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "results": [
      {
        "filename": "src/auth.py",
        "content": "def authenticate_user(username, password):\n    \"\"\"Authenticate user credentials against the database.\"\"\"\n    user = User.query.filter_by(username=username).first()\n    if user and bcrypt.check_password_hash(user.password_hash, password):\n        return user\n    return None",
        "score": 0.94
      },
      {
        "filename": "src/models/user.py",
        "content": "class User(db.Model):\n    id = db.Column(db.Integer, primary_key=True)\n    username = db.Column(db.String(80), unique=True, nullable=False)\n    password_hash = db.Column(db.String(128), nullable=False)",
        "score": 0.87
      }
    ],
    "hash": "a3f82c1d4e9b6f028571d3a2c8e4b96f7d2e5a18",
    "pending_embeddings": 0
  }
  ```
</ResponseExample>