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

# Search

> Build retrieval workflows and search experiences with Bulkgrid search.

Use search when the content is already indexed and you want ranked results immediately.

## When search is the right tool

Search is the right fit when you need:

* low-latency retrieval
* result ranking for application search
* grounding material for answer generation
* collection-scoped access to existing content

## Request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "$BULKGRID_BASE_URL/api/v1/search" \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $BULKGRID_API_KEY" \
    -d '{
      "query": "bulkgrid crawl options",
      "limit": 10,
      "fullTextWeight": 0.3,
      "semanticWeight": 0.7,
      "rrfK": 60
    }'
  ```

  ```js Node.js theme={null}
  import { BulkgridApiError, BulkgridClient } from '@bulkgrid/sdk';

  const client = new BulkgridClient({
    apiKey: process.env.BULKGRID_API_KEY ?? '',
    baseUrl: process.env.BULKGRID_BASE_URL ?? '',
  });

  try {
    const data = await client.search({
      query: 'bulkgrid crawl options',
      limit: 10,
      fullTextWeight: 0.3,
      semanticWeight: 0.7,
      rrfK: 60,
    });
  } catch (error) {
    if (error instanceof BulkgridApiError) {
      console.error(error.status, error.data);
    }
    throw error;
  }
  ```
</CodeGroup>

## Ranking controls

Bulkgrid currently exposes three main ranking controls:

* `fullTextWeight`
* `semanticWeight`
* `rrfK`

Use the defaults first. Tune only when you have a specific retrieval problem to solve.

### Practical tuning guidance

* increase `fullTextWeight` when exact keyword matches matter more
* increase `semanticWeight` for natural-language search behavior
* leave `rrfK` alone unless you are actively testing ranking behavior

## Response handling

Search returns:

* `query`
* `scoring`
* `results`
* `count`

Each result includes identifiers, source URL data, chunk text, ranking values, and metadata.

## Common product patterns

### Search UI

Show:

* `title`
* `url`
* trimmed `text_content`

Keep `score` available for debugging and ranking analysis.

### RAG or answer generation

Pass the top results into your answer-generation step with source URLs attached so the model can be grounded and the UI can cite sources.

### Scoped retrieval

Use `collectionId` when your application must restrict what corpus a user, workspace, or agent can search.

## Failure handling

* `400`: invalid payload or out-of-range values
* `401`: invalid or missing API key
* `429`: back off and retry with jitter