Python SDK

Install

pip install raily-ai

Python 3.10+. The import name is raily:

from raily import Raily, AsyncRaily, RailyError, RailyAuthError

Quickstart

import os
from raily import Raily

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

for hit in client.search("your search query", limit=5):
    print(f"{hit.score:.2f}  {hit.fields.get('title', '(untitled)')}")

Get the endpoint URL and key from your endpoint’s API access panel — see the SDK quickstart.

`Raily(...)`

client = Raily(
    api_key="rly_...",      # required
    endpoint="https://...", # required — your endpoint URL
    timeout=60.0,           # optional, seconds
)

Parameter	Type	Default	Description
`api_key`	`str`	—	The API key for your endpoint.
`endpoint`	`str`	—	Your endpoint URL.
`timeout`	`float`	`60.0`	Per-request timeout, in seconds.

The client holds no session state — construct it once and reuse it.

`search(query, limit=3)`

results = client.search("your search query", limit=5)

Parameter	Type	Default	Description
`query`	`str`	—	What to search for.
`limit`	`int`	`3`	Max results to return (up to 10; some endpoints cap lower). Fewer may come back.
`explain`	`bool`	`False`	Return a `SearchResult` (`hits` + `info`) instead of a bare list.

Returns a list[SearchHit] — or a SearchResult when explain=True (see Debugging empty results).

Debugging empty results

A search can legitimately return nothing — and a bare [] doesn’t say why. Pass explain=True to get the endpoint’s own message plus a hint:

res = client.search("articles", explain=True)
print(res.info.count)    # 0
print(res.info.message)  # the endpoint's summary, e.g. "No results found"
print(res.info.note)     # why, and what to try (only set when there are no hits)
for hit in res:          # SearchResult is iterable over hits
    ...

Or have the client log a one-line hint on every empty result during development:

client = Raily(api_key="rly_...", endpoint="https://...", debug=True)
# logs to the "raily" logger when a search returns nothing

SearchHit

Field	Type	Description
`score`	`float \| None`	Relevance score (higher is better).
`fields`	`dict[str, str]`	Your source’s display fields as a flat `{name: value}` map (see below).
`text`	`str \| None`	A plain-text summary of the result, when available.
`image_url`	`str \| None`	The result’s image, for image sources (otherwise `None`).
`is_relevant`	`bool \| None`	`False` for a lower-confidence result returned when there are few strong matches.
`source_collection`	`str \| None`	The source the result came from.
`id`	`str \| None`	Result id, when the source provides one.
`raw`	`dict`	The full original result, for anything not surfaced above.

Working with `fields`

fields is a flat {name: value} map of the display fields configured on your source — e.g. title, text, author, published_date. Read a value by name:

for hit in client.search("your search query", limit=5):
    print(hit.fields.get("title"), "—", hit.fields.get("published_date"))

A field with multiple values is joined with ", ". To see what your source exposes, print the whole map once:

for name, value in client.search("your search query", limit=1)[0].fields.items():
    print(name, "=", value)

Need the full original result (every field, untrimmed)? It’s on hit.raw.

Errors

from raily import Raily, RailyError, RailyAuthError

try:
    hits = client.search("your search query")
except RailyAuthError:
    ...  # key missing, invalid, expired, or not valid for this endpoint
except RailyError as exc:
    ...  # network / server / timeout
    print(f"Search failed: {exc}")

Exception	When	What to do
`RailyAuthError`	Key missing, invalid, expired, or for a different endpoint.	Check `RAILY_API_KEY` and that it was issued for this endpoint.
`RailyError`	Network, server, or timeout.	Retry with backoff; raise `timeout` for slow networks.

RailyAuthError is a subclass of RailyError, so catch it first.

Async

AsyncRaily has the same surface with await:

import asyncio
from raily import AsyncRaily

async def main():
    client = AsyncRaily(api_key="rly_...", endpoint="https://...")
    hits = await client.search("your search query", limit=5)
    print(len(hits))

asyncio.run(main())

Run many searches concurrently:

queries = ["batteries", "climate", "elections"]
results = await asyncio.gather(*(client.search(q, limit=3) for q in queries))

Recipe: a search endpoint with FastAPI

import os
from fastapi import FastAPI
from raily import AsyncRaily, RailyError

app = FastAPI()
raily = AsyncRaily(
    api_key=os.environ["RAILY_API_KEY"],
    endpoint=os.environ["RAILY_ENDPOINT"],
)

@app.get("/search")
async def search(q: str, limit: int = 5):
    try:
        hits = await raily.search(q, limit=limit)
    except RailyError:
        return {"results": []}
    return {
        "results": [
            {"score": h.score, "fields": h.fields, "source": h.source_collection}
            for h in hits
        ]
    }

Troubleshooting

No results came back (empty list)

An empty list is a valid answer, not an error. The usual causes, in order:

The query is too generic. Category words like "articles", "news", or "posts" carry no topical signal, so nothing matches strongly enough to return. Search a specific topic ("battery recycling", not "articles").
A freshness filter. Queries that imply recency ("latest", "news") apply a published_date cutoff — if your source’s data is older, that can remove everything. Drop the recency words or widen the range.
Your source has no data yet. A brand-new source may not have finished indexing yet. Search a term you know is in the data; if that’s also empty, confirm the source has finished indexing in the Raily app.

Use explain=True to see which it is:

res = client.search("articles", explain=True)
print(res.info.count, res.info.message, res.info.note)

“API key was rejected for this endpoint” (RailyAuthError)

The key is missing, wrong, expired, or was issued for a different endpoint. A key only works against the endpoint it was created on. Re-check RAILY_API_KEY and RAILY_ENDPOINT.

Searches are slow or time out

Raise the timeout (seconds) and retry. Reuse one client rather than constructing one per request.

Getting Started

Connect Data to AI

SDKs

Core Concepts

Features

Integrations

Install

Quickstart

`Raily(...)`

`search(query, limit=3)`

Debugging empty results

SearchHit

Working with `fields`

Errors

Async

Recipe: a search endpoint with FastAPI

Troubleshooting

​Install

​Quickstart

​Raily(...)

​search(query, limit=3)

​Debugging empty results

​SearchHit

​Working with fields

​Errors

​Async

​Recipe: a search endpoint with FastAPI

​Troubleshooting

Install

Quickstart

`Raily(...)`

`search(query, limit=3)`

Debugging empty results

SearchHit

Working with `fields`

Errors

Async

Recipe: a search endpoint with FastAPI

Troubleshooting