Search R2R

POST

1 from r2r import R2RClient
2 
3 client = R2RClient()
4 # if using auth, do client.login(...)
5 
6 # Basic mode, no overrides
7 response = client.retrieval.search(
8     query="Who is Aristotle?",
9     search_mode="basic"
10 )
11 
12 # Advanced mode with overrides
13 response = client.retrieval.search(
14     query="Who is Aristotle?",
15     search_mode="advanced",
16     search_settings={
17         "filters": {"document_id": {"$eq": "3e157b3a-..."}},
18         "limit": 5
19     }
20 )
21 
22 # Custom mode with full control
23 response = client.retrieval.search(
24     query="Who is Aristotle?",
25     search_mode="custom",
26     search_settings={
27         "use_semantic_search": True,
28         "filters": {"category": {"$like": "%philosophy%"}},
29         "limit": 20,
30         "chunk_settings": {"index_measure": "l2_distance"}
31     }
32 )

Play

200Successful

1 {
2   "results": {
3     "chunk_search_results": [
4       {
5         "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
6         "document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b",
7         "collection_ids": [
8           "collection_ids"
9         ],
10         "score": 0.23943702876567796,
11         "text": "Example text from the document",
12         "metadata": {
13           "associated_query": "What is the capital of France?",
14           "title": "example_document.pdf"
15         },
16         "owner_id": "2acb499e-8428-543b-bd85-0d9098718220"
17       }
18     ],
19     "graph_search_results": [
20       {
21         "content": {
22           "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
23           "name": "Entity Name",
24           "description": "Entity Description",
25           "metadata": {
26             "key": "value"
27           }
28         },
29         "result_type": "entity",
30         "chunk_ids": [
31           "c68dc72e-fc23-5452-8f49-d7bd46088a96"
32         ],
33         "metadata": {
34           "associated_query": "What is the capital of France?"
35         }
36       }
37     ],
38     "web_search_results": [
39       {
40         "title": "Page Title",
41         "link": "https://example.com/page",
42         "snippet": "Page snippet",
43         "position": 1,
44         "date": "2021-01-01",
45         "sitelinks": [
46           {
47             "link": "https://example.com/sitelink",
48             "title": "Sitelink Title"
49           }
50         ]
51       }
52     ],
53     "context_document_results": [
54       {
55         "document": {
56           "chunks": [
57             "Chunk 1",
58             "Chunk 2"
59           ],
60           "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
61           "metadata": {},
62           "title": "Document Title"
63         }
64       }
65     ]
66   }
67 }

Perform a search query against vector and/or graph-based databases.

Search Modes:

basic: Defaults to semantic search. Simple and easy to use.
advanced: Combines semantic search with full-text search for more comprehensive results.
custom: Complete control over how search is performed. Provide a full SearchSettings object.

Filters: Apply filters directly inside search_settings.filters. For example:

1 {
2   "filters": {"document_id": {"$eq": "3e157b3a-..."}}
3 }

Supported operators: $eq, $neq, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin.

Limit: Control how many results you get by specifying limit inside search_settings. For example:

1 {
2   "limit": 20
3 }

Examples:

Using basic mode and no overrides: Just specify search_mode="basic".
Using advanced mode and applying a filter: Specify search_mode="advanced" and include search_settings={"filters": {...}, "limit": 5} to override defaults.
Using custom mode: Provide the entire search_settings to define your search exactly as you want it.

Request

This endpoint expects an object.

querystringRequired

Search query to find relevant documents

search_modeenumOptional

Default value of custom allows full control over search settings.

Pre-configured search modes: basic: A simple semantic-based search. advanced: A more powerful hybrid search combining semantic and full-text. custom: Full control via search_settings.

If filters or limit are provided alongside basic or advanced, they will override the default settings for that mode.

Allowed values:

search_settingsobjectOptional

The search configuration object. If search_mode is custom, these settings are used as-is. For basic or advanced, these settings will override the default mode configuration.

Common overrides include filters to narrow results and limit to control how many results are returned.

Response

Successful Response

resultsobject

Result of an aggregate search operation.

Search R2R

Headers

Request

Response

Errors