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

# Search with the SDK

> Call your search endpoint from your code with the Python or TypeScript SDK.

Call your Raily endpoint from your own code — a backend service or an agent you build —
with a typed client. Install it, add your key, and run a search.

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="/sdks/python">
    `pip install raily-ai`
  </Card>

  <Card title="TypeScript / JavaScript" icon="js" href="/sdks/javascript">
    `npm install @raily/sdk`
  </Card>
</CardGroup>

## Get your endpoint URL and key

An endpoint is your authenticated search URL — create one in the Raily app. It needs two
things to call: the endpoint URL and an API key.

<Steps>
  <Step title="Open an endpoint">
    In the Raily app, open an endpoint (or create one). Its page shows the **endpoint URL**.
  </Step>

  <Step title="Create an API key">
    Under **API access**, click **Create key**. The full key is shown **once** — copy it now.
  </Step>

  <Step title="Set them in your environment">
    Keep the key out of source control — load it from an environment variable.

    ```bash theme={null}
    export RAILY_ENDPOINT="https://endpoints.app.raily.ai/t/your-workspace/123/mcp"
    export RAILY_API_KEY="rly_..."
    ```
  </Step>
</Steps>

## Run your first search

<CodeGroup>
  ```python Python theme={null}
  import os
  from raily import Raily

  client = Raily(
      api_key=os.environ["RAILY_API_KEY"],
      endpoint=os.environ["RAILY_ENDPOINT"],
  )

  results = client.search("your search query", limit=5)
  print(f"{len(results)} results\n")

  for hit in results:
      # `fields` is a flat {name: value} map of your source's display fields
      title = hit.fields.get("title", "(untitled)")
      print(f"- {title}  (score {hit.score:.2f})")
  ```

  ```typescript TypeScript theme={null}
  import { Raily } from "@raily/sdk";

  const client = new Raily({
    apiKey: process.env.RAILY_API_KEY!,
    endpoint: process.env.RAILY_ENDPOINT!,
  });

  const results = await client.search("your search query", { limit: 5 });
  console.log(`${results.length} results\n`);

  for (const hit of results) {
    // `fields` is a flat { name: value } map of your source's display fields
    const title = hit.fields.title ?? "(untitled)";
    console.log(`- ${title}  (score ${hit.score?.toFixed(2)})`);
  }
  ```
</CodeGroup>

```text Output theme={null}
5 results

- Tech Giants Report Record Q1 Earnings Amid AI Investment Surge  (score 0.66)
- Researchers Achieve Breakthrough in Solid-State Battery Technology  (score 0.65)
- Scientists Discover New Deep-Sea Species Off the Coast of New Zealand  (score 0.63)
- Inside the Global Race to Map the Ocean Floor  (score 0.63)
- Global Leaders Convene for Emergency Climate Summit  (score 0.62)
```

<Note>
  Each result's content lives in **`fields`** — a flat `{name: value}` map of the display
  fields configured on your source (e.g. `title`, `text`, `author`, `published_date`). See
  [Reading results](#reading-results).
</Note>

## Reading results

`search()` returns a list of results. Each has a `score`, the `source_collection` it came
from, and **`fields`** — a flat map of your source's display fields. Read a value by name,
or walk the whole map to see what your source exposes:

<CodeGroup>
  ```python Python theme={null}
  for hit in client.search("your search query", limit=5):
      print(f"score {hit.score:.2f}  from {hit.source_collection}")
      for name, value in hit.fields.items():
          print(f"  {name}: {value}")
  ```

  ```typescript TypeScript theme={null}
  for (const hit of await client.search("your search query", { limit: 5 })) {
    console.log(`score ${hit.score?.toFixed(2)}  from ${hit.source_collection}`);
    for (const [name, value] of Object.entries(hit.fields)) {
      console.log(`  ${name}: ${value}`);
    }
  }
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdks/python">
    Reference, async, errors, recipes
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/javascript">
    Reference, errors, recipes
  </Card>
</CardGroup>