Query Operations
Execute queries across tables using full-text search, vector similarity search, or hybrid approaches combining both with Reciprocal Rank Fusion (RRF).
Query Types
Full-Text Search
Uses Antfly query syntax for powerful text searching:
- Field-specific queries:
body:computer - Boolean operators:
AND,OR,NOT - Range queries:
year:>2020 - Phrase queries:
"exact phrase"
Semantic Search
Natural language queries using vector similarity:
- Searches across specified embedding indexes
- Returns semantically similar documents
- Supports multiple embedding models
Hybrid Search (RRF)
Combines full-text and semantic search using Reciprocal Rank Fusion:
{
"full_text_search": {"query": "body:computer"},
"semantic_search": "artificial intelligence",
"indexes": ["title_body_nomic"]
}
Filtering and Exclusion
Refine results with powerful filtering:
Filter Prefix
Only return documents whose keys start with a specific string:
{"filter_prefix": "user:"}
Returns only keys like "user:123", "user:456"
Filter Query
Apply an Antfly query as an AND condition:
{"filter_query": {"query": "+category:technology +year:>2020"}}
Documents must match both the main query and filter query.
Exclusion Query
Exclude documents matching an Antfly query (NOT condition):
{"exclusion_query": {"query": "category:deprecated OR status:archived"}}
Performance Note: All filters are applied before scoring and ranking, improving query performance.
RAG (Retrieval-Augmented Generation)
Execute queries and generate summaries using LLMs:
- Supports multiple retrieval queries
- Streams results as Server-Sent Events (SSE)
- Returns markdown summaries with inline citations
- Combines results from multiple tables
Retrieval Agent
Intelligent query routing with automatic query generation:
- Classifies queries as "question" or "search"
- Generates optimal search queries across tables
- Returns generated responses (for questions) or document IDs (for searches)
- Streams classification, keywords, queries, and results
Improving Search Relevance
Antfly provides several techniques to improve search result quality:
1. Hybrid Search (Combine Full-Text + Semantic)
Use both full_text_search and semantic_search together. Results are merged using
Reciprocal Rank Fusion (RRF) to balance keyword matching and semantic similarity.
2. Reranking
Apply a cross-encoder model to re-score results based on query-document relevance. Rerankers are more accurate than embedding models but slower, so use them on already-filtered results (e.g., top 50-100).
{
"semantic_search": "gaming laptops",
"limit": 10,
"reranker": {
"provider": "antfly",
"model": "mixedbread-ai/mxbai-rerank-base-v1",
"field": "description",
"candidate_count": 100
}
}
3. Result Pruning
Filter out low-quality results by detecting score gaps or setting minimum thresholds:
{
"semantic_search": "machine learning",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30.0
}
}
min_score_ratio: Keep only results scoring at least X% of the top resultmax_score_gap_percent: Stop when a consecutive score gap exceeds X% of the total score range
4. Merge Strategies
Choose how full-text and semantic results are combined:
rrf(default): Reciprocal Rank Fusion - balanced, works well in most casesrsf: Relative Score Fusion - normalizes and weights scores differently
5. Query Filtering
Use filter_query and filter_prefix to pre-filter before scoring, improving
both performance and relevance by removing irrelevant documents early.
Best Practice: Combine techniques for optimal results:
- Start with hybrid search (full-text + semantic)
- Apply filters to narrow the domain
- Use reranker on top results
- Apply pruner to remove outliers
Perform a global query
POST
/queryExecutes a query across all relevant tables and shards based on the query content.
Query Examples
Full-text search:
{
"table": "wikipedia",
"full_text_search": {"query": "body:computer"},
"limit": 10
}
Semantic search:
{
"table": "articles",
"semantic_search": "artificial intelligence applications",
"indexes": ["title_body_embedding"],
"limit": 20
}
Hybrid search (RRF):
{
"table": "products",
"full_text_search": {"query": "laptop gaming"},
"semantic_search": "high performance gaming computers",
"indexes": ["product_embedding"],
"filter_query": {"query": "+price:<2000 +in_stock:true"},
"fields": ["name", "price", "description"],
"limit": 15
}
With filtering:
{
"table": "users",
"filter_prefix": "tenant:acme:",
"full_text_search": {"query": "active:true"},
"exclusion_query": {"query": "status:deleted"},
"limit": 50
}
NDJSON format:
For bulk queries, send multiple queries as NDJSON with Content-Type: application/x-ndjson.
Each line must end with \n:
{"table":"wiki","semantic_search":"AI","indexes":["emb"],"limit":5}
{"table":"docs","full_text_search":{"query":"tutorial"},"limit":10}
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
Code Examples
curl -X POST "/db/v1/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}'const response = await fetch('/db/v1/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
});
const data = await response.json();fetch('/db/v1/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/query',
headers=headers,
json={
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}`)
req, _ := http.NewRequest("POST", "/db/v1/query", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"responses": [
{
"source_ranking": "rrf",
"next_source_cursor": "string",
"remote_snapshot": "string",
"evaluation": {},
"hits": {
"total": {
"value": 0,
"relation": "exact"
},
"hits": [
{
"_table": "string",
"_computed": {},
"_id": "string",
"_score": 0,
"_distance": 0,
"_index_scores": {},
"_score_details": {
"graph_metric_rerank": {
"index_name": "string",
"metric_name": "string",
"base_score": 0,
"base_weight": 0,
"metric_score": 0,
"metric_score_used": 0,
"metric_weight": 0,
"missing_score_used": true,
"final_score": 0,
"published_generation": 0
}
},
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"matched_artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
},
"evidence": {
"local_id": "string",
"decision": "string",
"confidence": 0,
"source_artifact": "string",
"source_artifact_key": "string",
"resolution_artifact": "string",
"resolution_artifact_key": "string",
"resolver": "string",
"resolver_table": "string",
"mention": {},
"canonical": {}
},
"matches": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
],
"position": "string",
"revision": "string",
"chunks": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
]
},
"_sort": [
null
],
"_highlights": {}
}
],
"max_score": 0
},
"aggregations": {},
"analyses": {},
"graph_metric_results": {},
"profile": {
"value_verification": {
"documents": 0,
"bytes": 0,
"verification_metrics_version": 0,
"source_read_us": 0,
"source_parse_us": 0,
"source_batches": 0,
"source_scalar_reads": 0,
"projected_sources": 0,
"stored_field_sources": 0,
"batch_refusals": 0,
"batch_peak_bytes": 0,
"plans": [
{
"operation": "equals",
"field": "string",
"candidate_field": "string",
"index": "string",
"verification": "original_value",
"fallback_reason": "string"
}
]
},
"shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"join": {
"strategy_used": "broadcast",
"left_rows_scanned": 0,
"right_rows_scanned": 0,
"rows_matched": 0,
"rows_unmatched_left": 0,
"rows_unmatched_right": 0,
"duration_ms": 0
},
"reranker": {
"provider": "antfly",
"model": "string",
"documents_reranked": 0,
"duration_ms": 0
},
"merge": {
"strategy": "rrf",
"full_text_hits": 0,
"semantic_hits": 0,
"duration_ms": 0
},
"graph_metrics": [
{
"query_name": "string",
"source": "string",
"index_name": "string",
"metric_name": "string",
"freshness": "string",
"status": {
"state": "string",
"phase": "idle",
"edge_filter": {
"mode": "all",
"types": [
"string"
]
},
"metadata_version": 0,
"config_fingerprint": "string",
"maintenance_paused": true,
"build_queued": true,
"published_generation": 0,
"edge_generation": 0,
"target_edge_generation": 0,
"queued_generation": 0,
"building_generation": 0,
"build_job_id": 0,
"build_started_at_ms": 0,
"build_iteration": 0,
"build_lease_expires_at_ms": 0,
"build_worker_id": "string",
"build_cursor": "string",
"build_completed_units": 0,
"build_total_units": 0,
"build_pages": [
{
"phase": "string",
"iteration": 0,
"page_id": 0,
"state": "pending",
"range_kind": "full",
"worker_id": "string",
"lease_expires_at_ms": 0,
"attempt": 0,
"cursor": "string",
"completed_units": 0,
"total_units": 0,
"last_error": "string"
}
],
"build_pages_truncated": true,
"retry_count": 0,
"last_error": "string",
"progress": 0,
"converged": true,
"iterations_completed": 0,
"delta": 0,
"computed_at_ms": 0,
"last_event": {
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
},
"recent_events": [
{
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
}
]
}
}
],
"sort": {
"plan": "string",
"order_by": [
{
"field": "string",
"desc": true
}
],
"cursor": "string",
"exactness": "string",
"source": "string",
"candidate_source": "none",
"cursor_support": "string",
"source_load": "string",
"distributed_behavior": "string",
"selection_reason": "string",
"require_native": true,
"sort_lifecycle_state": "unsupported",
"index_sort_coverage": "string",
"candidate_count": 0,
"ordered_scanned_count": 0,
"cursor_rejected_count": 0,
"selected_count": 0,
"total_us": 0,
"distributed_shard_count": 0,
"budget_rejection_reason": "string",
"sort_rejection_reason": "string",
"sort_rejection_detail": "string",
"sort_rejection_field": "string"
}
},
"took": 0,
"status": 0,
"error": "string",
"table": "string"
}
]
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
Standalone evaluation endpoint
POST
/evalRun evaluators on provided data without executing a query. Useful for testing evaluators, evaluating cached results, or batch evaluation.
Retrieval metrics (require ground_truth.relevant_ids and retrieved_ids):
- recall, precision, ndcg, mrr, map
LLM-as-judge metrics (require judge config):
- relevance, faithfulness, completeness, coherence, safety, helpfulness, correctness, citation_quality
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
}
Code Examples
curl -X POST "/db/v1/eval" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
}'const response = await fetch('/db/v1/eval', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
})
});
const data = await response.json();fetch('/db/v1/eval', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/eval',
headers=headers,
json={
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
},
"query": "string",
"output": "string",
"context": [
{}
],
"retrieved_ids": [
"string"
]
}`)
req, _ := http.NewRequest("POST", "/db/v1/eval", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"scores": {
"retrieval": {},
"generation": {}
},
"summary": {
"average_score": 0,
"passed": 0,
"failed": 0,
"total": 0
},
"duration_ms": 0
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}Build a search query from natural language
POST
/agents/query-builderUses an LLM to translate natural language search intent into a structured Antfly query. The generated query can be used directly in the QueryRequest.full_text_search or filter_query fields.
This endpoint is useful for:
- Building queries from user descriptions
- Generating example queries for a table's schema
- Agentic retrieval in RAG pipelines
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
}
Code Examples
curl -X POST "/db/v1/agents/query-builder" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
}'const response = await fetch('/db/v1/agents/query-builder', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
})
});
const data = await response.json();fetch('/db/v1/agents/query-builder', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/agents/query-builder',
headers=headers,
json={
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"example_documents": [
{}
],
"table": "articles",
"intent": "Find all published articles about machine learning from the last year",
"schema_fields": [
"title",
"content",
"status",
"published_at"
],
"mode": "auto",
"output": "query_request",
"constraints": {
"limit": 10,
"require_executable": true,
"prefer_indexes": [
"body_embedding"
]
},
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
}
}`)
req, _ := http.NewRequest("POST", "/db/v1/agents/query-builder", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"session_id": "string",
"iteration": 0,
"clarification_count": 0,
"status": "clarification_required",
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"remaining_internal_iterations": 0,
"remaining_user_clarifications": 0,
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"query": {
"conjuncts": [
{
"match": "machine learning",
"field": "content"
},
{
"term": "published",
"field": "status"
}
]
},
"query_request": {
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
},
"retrieval_query_request": {
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
},
"retrieval_navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"specialist": "full_text",
"plan": {},
"explanation": "Searches for 'machine learning' in content field AND requires status to be exactly 'published'",
"confidence": 0.85,
"warnings": [
"Field 'category' not found in schema, using content field instead"
]
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}No response body
Retrieval Agent - Agentic document retrieval with tool calling
POST
/agents/retrievalUses a DFA-based approach to retrieve documents: clarify → select_strategy → refine_query → execute
Key Features:
- Multi-strategy: Semantic, BM25, tree, graph, metadata, or hybrid
- Query Pipeline: Chain queries with references (e.g., tree search starting from semantic results)
- Clarification: Optional multi-turn for query disambiguation
- Reasoning Chain: Returns steps taken during retrieval
Strategies:
semantic: Vector similarity search using embeddingsbm25: Full-text search with BM25 scoringmetadata: Structured field queriestree: Iterative tree navigation with summarization (PageIndex-style)graph: Relationship-based traversalhybrid: Combine strategies with RRF or rerank
SSE Event Types:
step_started: Pipeline step began (see SSEStepStarted schema)step_progress: Progress within a step (see SSEStepProgress schema)step_completed: Pipeline step finished (see SSEStepCompleted schema)classification: Query classification result (see ClassificationTransformationResult)reasoning: Streamed reasoning text chunk (string)followup: Generated follow-up question (string)hit: Individual document result (see QueryHit)tool_mode: Tool calling mode selected (see SSEToolMode)eval: Evaluation metrics (see EvalResult)done: Retrieval complete (see RetrievalAgentResult)doneis the authoritative final bounded-agent envelope for both JSON and SSE consumerserror: Error occurred (see SSEError)
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
}
Code Examples
curl -X POST "/db/v1/agents/retrieval" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
}'const response = await fetch('/db/v1/agents/retrieval', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
})
});
const data = await response.json();fetch('/db/v1/agents/retrieval', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/agents/retrieval',
headers=headers,
json={
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"query": "How do I configure OAuth?",
"queries": [
{
"table": "docs",
"semantic_search": "How do I configure OAuth?",
"indexes": [
"doc_embeddings"
],
"limit": 10
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "This collection contains API documentation for the Acme product suite.",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"max_internal_iterations": 0,
"max_user_clarifications": 0,
"require_decision_after": 0,
"max_context_tokens": 0,
"reserve_tokens": 4000,
"stream": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"classification": {
"enabled": true,
"with_reasoning": true,
"force_strategy": "simple",
"force_semantic_mode": "rewrite"
},
"retrieval": {
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
},
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
}
},
"generation": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"system_prompt": "string",
"generation_context": "Be concise and technical. Include code examples where relevant."
},
"followup": {
"enabled": true,
"count": 1
},
"confidence": {
"enabled": true
},
"eval": {
"evaluators": [
"recall"
],
"judge": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"ground_truth": {
"relevant_ids": [
"string"
],
"expectations": "string"
},
"options": {
"k": 1,
"pass_threshold": 0,
"timeout_seconds": 1
}
}
},
"document_renderer": "{{encodeToon this.fields}}"
}`)
req, _ := http.NewRequest("POST", "/db/v1/agents/retrieval", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"id": "ragr_cr3ig20h5tbs73e3ahrg",
"model": "gemini-2.0-flash",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_internal_iterations"
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"total_tokens": 0,
"cached_input_tokens": 0,
"llm_calls": 0,
"resources_retrieved": 0,
"prune_stats": {
"resources_kept": 0,
"resources_pruned": 0,
"tokens_kept": 0,
"tokens_pruned": 0
}
},
"hits": [
{
"_table": "string",
"_computed": {},
"_id": "string",
"_score": 0,
"_distance": 0,
"_index_scores": {},
"_score_details": {
"graph_metric_rerank": {
"index_name": "string",
"metric_name": "string",
"base_score": 0,
"base_weight": 0,
"metric_score": 0,
"metric_score_used": 0,
"metric_weight": 0,
"missing_score_used": true,
"final_score": 0,
"published_generation": 0
}
},
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"matched_artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
},
"evidence": {
"local_id": "string",
"decision": "string",
"confidence": 0,
"source_artifact": "string",
"source_artifact_key": "string",
"resolution_artifact": "string",
"resolution_artifact_key": "string",
"resolver": "string",
"resolver_table": "string",
"mention": {},
"canonical": {}
},
"matches": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
],
"position": "string",
"revision": "string",
"chunks": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
]
},
"_sort": [
null
],
"_highlights": {}
}
],
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"strategy_used": "semantic",
"session_id": "string",
"iteration": 0,
"clarification_count": 0,
"remaining_internal_iterations": 0,
"remaining_user_clarifications": 0,
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"applied_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"tool_calls_made": 0,
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"classification": {
"route_type": "question",
"strategy": "simple",
"semantic_mode": "rewrite",
"improved_query": "string",
"semantic_query": "string",
"step_back_query": "string",
"sub_questions": [
"string"
],
"multi_phrases": [
"string"
],
"reasoning": "string",
"confidence": 0
},
"generation": "string",
"generation_confidence": 0,
"context_relevance": 0,
"followup_questions": [
"string"
],
"eval_result": {
"scores": {
"retrieval": {},
"generation": {}
},
"summary": {
"average_score": 0,
"passed": 0,
"failed": 0,
"total": 0
},
"duration_ms": 0
}
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}No response body
No response body
No response body
No response body
{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}No response body
No response body
No response body
Research Agent - Bounded multi-phase research with a cited report
POST
/agents/researchRuns a bounded research state machine: plan → research (parallel retrieval researchers) → reflect → … → write → verify
Every researcher is an ordinary retrieval-agent run over the request's
authorized queries, so authorization, mandatory predicates and tool
policy are identical to /agents/retrieval. Researchers return
compressed findings; the writer only sees findings and a deduplicated
evidence registry, and the server validates every [E#] citation.
All work is bounded by budget. Send research_state back to resume
or extend a run. For runs longer than one request, use
/agents/research/jobs.
SSE Event Types: the retrieval-agent events are reused.
step_progress carries phase values plan, sub_question_started,
finding, reflection, section and verification. Report text
streams as generation. done carries the authoritative
ResearchAgentResult.
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
}
Code Examples
curl -X POST "/db/v1/agents/research" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
}'const response = await fetch('/db/v1/agents/research', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
})
});
const data = await response.json();fetch('/db/v1/agents/research', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/agents/research',
headers=headers,
json={
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
}`)
req, _ := http.NewRequest("POST", "/db/v1/agents/research", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}{
"code": "string",
"error": "An error message",
"message": "string",
"retryable": true,
"retry_after_ms": 1
}No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
Start a durable research job
POST
/agents/research/jobsPersists a research request as a durable job that advances one bounded phase at a time. Each phase checkpoints its research_state, so a job survives server restarts and can be resumed by any caller holding the same identity. Jobs are scoped to the authenticated principal.
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
}
Code Examples
curl -X POST "/db/v1/agents/research/jobs" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
}'const response = await fetch('/db/v1/agents/research/jobs', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
})
});
const data = await response.json();fetch('/db/v1/agents/research/jobs', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/agents/research/jobs',
headers=headers,
json={
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"request": {
"query": "How do Antfly's hybrid search and reranking interact, and what are the tuning trade-offs?",
"queries": [
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
],
"messages": [
{
"role": "user",
"content": "string",
"tool_calls": [
{
"id": "string",
"type": "function",
"function": {
"name": "string",
"arguments": "string"
}
}
],
"tool_call_id": "string",
"name": "string"
}
],
"agent_knowledge": "string",
"accumulated_filters": [
{
"field": "string",
"operator": "eq",
"value": null
}
],
"session_id": "string",
"decisions": [
{
"question_id": "string",
"answer": null,
"approved": true
}
],
"interactive": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"steps": {
"plan": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"research": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"tools": {
"enabled_tools": [
"add_filter",
"semantic_search",
"web_search"
],
"web_search_config": {
"provider": "exa",
"api_key": "string",
"endpoint": "string",
"project_id": "string",
"location": "string",
"data_store": "string",
"serving_config": "string",
"credentials_path": "string",
"max_results": 1,
"timeout_ms": 0,
"safe_search": true,
"language": "en",
"region": "us",
"include_content": true,
"include_highlights": true
},
"web_search_connection": "string",
"fetch_config": {
"s3_credentials": {
"endpoint": "s3.amazonaws.com",
"use_ssl": true,
"access_key_id": "your-access-key-id",
"secret_access_key": "your-secret-access-key",
"session_token": "your-session-token"
},
"max_content_length": 0,
"allowed_hosts": [
"string"
],
"block_private_ips": true,
"max_download_size_bytes": 0,
"timeout_seconds": 0
},
"max_tool_iterations": 1
},
"navigation": {
"query_index": 0,
"strategy": "tree",
"selection": "agentic",
"max_depth": 1,
"beam_width": 1,
"index": "string",
"start_nodes": "string",
"start_key": "string",
"direction": "out",
"edge_types": [
"string"
],
"max_steps": 1,
"neighbor_limit": 1,
"instruction": "string",
"instruction_field": "string"
}
},
"reflect": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
},
"write": {
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string",
"outline": [
"string"
]
},
"verify": {
"enabled": true,
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"chain": [
{
"generator": {
"provider": "openai",
"model": "gpt-4.1",
"temperature": 0.7,
"max_tokens": 2048
},
"retry": {
"max_attempts": 1,
"initial_backoff_ms": 100,
"backoff_multiplier": 1,
"max_backoff_ms": 0
},
"condition": "always"
}
],
"instructions": "string"
}
},
"budget": {
"max_rounds": 1,
"max_sub_questions": 1,
"max_parallel": 1,
"researcher_iterations": 1,
"researcher_tool_calls": 1,
"max_llm_calls": 3,
"max_tool_calls": 1,
"max_evidence": 1,
"max_report_tokens": 256,
"deadline_ms": 1000
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"max_context_tokens": 0,
"reserve_tokens": 0,
"stream": true
},
"advance": 0
}`)
req, _ := http.NewRequest("POST", "/db/v1/agents/research/jobs", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"job_id": "string",
"state": "queued",
"phase": "plan",
"query": "string",
"advances": 0,
"cancel_requested": true,
"last_error": "string",
"created_at_ms": 0,
"updated_at_ms": 0,
"expires_at_ms": 0,
"result": {
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}
}No response body
No response body
No response body
No response body
No response body
No response body
Get a durable research job
GET
/agents/research/jobs/{jobId}Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Code Examples
curl -X GET "/db/v1/agents/research/jobs/{jobId}" \
-H "Authorization: Bearer YOUR_API_KEY"const response = await fetch('/db/v1/agents/research/jobs/{jobId}', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();fetch('/db/v1/agents/research/jobs/{jobId}', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.get('/db/v1/agents/research/jobs/{jobId}', headers=headers)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "/db/v1/agents/research/jobs/{jobId}", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"job_id": "string",
"state": "queued",
"phase": "plan",
"query": "string",
"advances": 0,
"cancel_requested": true,
"last_error": "string",
"created_at_ms": 0,
"updated_at_ms": 0,
"expires_at_ms": 0,
"result": {
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}
}No response body
No response body
No response body
Advance a durable research job
POST
/agents/research/jobs/{jobId}/advanceRuns up to max_phases bounded research phases and persists the
checkpoint after each one. Concurrent advances of the same job are
rejected with 409.
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"max_phases": 1
}
Code Examples
curl -X POST "/db/v1/agents/research/jobs/{jobId}/advance" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"max_phases": 1
}'const response = await fetch('/db/v1/agents/research/jobs/{jobId}/advance', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"max_phases": 1
})
});
const data = await response.json();fetch('/db/v1/agents/research/jobs/{jobId}/advance', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"max_phases": 1
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/agents/research/jobs/{jobId}/advance',
headers=headers,
json={
"max_phases": 1
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"max_phases": 1
}`)
req, _ := http.NewRequest("POST", "/db/v1/agents/research/jobs/{jobId}/advance", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"job_id": "string",
"state": "queued",
"phase": "plan",
"query": "string",
"advances": 0,
"cancel_requested": true,
"last_error": "string",
"created_at_ms": 0,
"updated_at_ms": 0,
"expires_at_ms": 0,
"result": {
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}
}{
"job_id": "string",
"state": "queued",
"phase": "plan",
"query": "string",
"advances": 0,
"cancel_requested": true,
"last_error": "string",
"created_at_ms": 0,
"updated_at_ms": 0,
"expires_at_ms": 0,
"result": {
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}
}No response body
No response body
No response body
No response body
No response body
No response body
No response body
Cancel a durable research job
POST
/agents/research/jobs/{jobId}/cancelProvide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Code Examples
curl -X POST "/db/v1/agents/research/jobs/{jobId}/cancel" \
-H "Authorization: Bearer YOUR_API_KEY"const response = await fetch('/db/v1/agents/research/jobs/{jobId}/cancel', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();fetch('/db/v1/agents/research/jobs/{jobId}/cancel', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post('/db/v1/agents/research/jobs/{jobId}/cancel', headers=headers)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "/db/v1/agents/research/jobs/{jobId}/cancel", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"job_id": "string",
"state": "queued",
"phase": "plan",
"query": "string",
"advances": 0,
"cancel_requested": true,
"last_error": "string",
"created_at_ms": 0,
"updated_at_ms": 0,
"expires_at_ms": 0,
"result": {
"id": "resr_cr3ig20h5tbs73e3ahrg",
"model": "string",
"created_at": 0,
"status": "clarification_required",
"incomplete_details": {
"reason": "max_rounds",
"message": "string"
},
"phase": "plan",
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
},
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"research_state": {
"signature": "string",
"phase": "plan",
"round": 0,
"plan": {
"brief": "string",
"sub_questions": [
{
"id": "q1",
"question": "string",
"rationale": "string",
"sources": [
"tables"
],
"round": 0,
"status": "pending"
}
],
"success_criteria": [
"string"
]
},
"findings": [
{
"sub_question_id": "string",
"question": "string",
"summary": "string",
"claims": [
{
"text": "string",
"evidence_ids": [
"string"
]
}
],
"open_questions": [
"string"
],
"evidence_ids": [
"string"
],
"status": "clarification_required",
"round": 0,
"llm_calls": 0,
"tool_calls": 0
}
],
"evidence": [
{
"id": "E3",
"source": "table",
"table": "string",
"doc_id": "string",
"url": "string",
"title": "string",
"snippet": "string",
"score": 0,
"sub_question_ids": [
"string"
]
}
],
"reflections": [
{
"round": 0,
"done": true,
"gaps": [
"string"
],
"contradictions": [
"string"
],
"new_sub_questions": [
"string"
]
}
],
"report": {
"title": "string",
"summary": "string",
"sections": [
{
"heading": "string",
"markdown": "string"
}
],
"markdown": "string"
},
"citations": [
{
"marker": "string",
"evidence_id": "string",
"section_index": 0,
"count": 0
}
],
"verification": {
"checked_sections": 0,
"unresolved_markers": [
"string"
],
"uncited_sections": [
0
],
"unsupported": [
{
"section_index": 0,
"text": "string",
"evidence_ids": [
"string"
],
"reason": "string"
}
],
"supported_ratio": 0
},
"usage": {
"llm_calls": 0,
"tool_calls": 0,
"researcher_runs": 0,
"rounds": 0,
"evidence_count": 0,
"elapsed_ms": 0
}
},
"steps": [
{
"id": "string",
"kind": "tool_call",
"name": "string",
"action": "string",
"status": "success",
"error_message": "string",
"duration_ms": 0,
"details": {}
}
],
"questions": [
{
"id": "clarify_oauth_version",
"kind": "confirm",
"question": "string",
"reason": "string",
"options": [
"string"
],
"default_answer": "string",
"affects": [
"string"
]
}
],
"session_id": "string"
}
}No response body
No response body
No response body
Query a specific table
POST
/tables/{tableName}/queryProvide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
Code Examples
curl -X POST "/db/v1/tables/{tableName}/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}'const response = await fetch('/db/v1/tables/{tableName}/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
});
const data = await response.json();fetch('/db/v1/tables/{tableName}/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/tables/{tableName}/query',
headers=headers,
json={
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}`)
req, _ := http.NewRequest("POST", "/db/v1/tables/{tableName}/query", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"responses": [
{
"source_ranking": "rrf",
"next_source_cursor": "string",
"remote_snapshot": "string",
"evaluation": {},
"hits": {
"total": {
"value": 0,
"relation": "exact"
},
"hits": [
{
"_table": "string",
"_computed": {},
"_id": "string",
"_score": 0,
"_distance": 0,
"_index_scores": {},
"_score_details": {
"graph_metric_rerank": {
"index_name": "string",
"metric_name": "string",
"base_score": 0,
"base_weight": 0,
"metric_score": 0,
"metric_score_used": 0,
"metric_weight": 0,
"missing_score_used": true,
"final_score": 0,
"published_generation": 0
}
},
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"matched_artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
},
"evidence": {
"local_id": "string",
"decision": "string",
"confidence": 0,
"source_artifact": "string",
"source_artifact_key": "string",
"resolution_artifact": "string",
"resolution_artifact_key": "string",
"resolver": "string",
"resolver_table": "string",
"mention": {},
"canonical": {}
},
"matches": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
],
"position": "string",
"revision": "string",
"chunks": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
]
},
"_sort": [
null
],
"_highlights": {}
}
],
"max_score": 0
},
"aggregations": {},
"analyses": {},
"graph_metric_results": {},
"profile": {
"value_verification": {
"documents": 0,
"bytes": 0,
"verification_metrics_version": 0,
"source_read_us": 0,
"source_parse_us": 0,
"source_batches": 0,
"source_scalar_reads": 0,
"projected_sources": 0,
"stored_field_sources": 0,
"batch_refusals": 0,
"batch_peak_bytes": 0,
"plans": [
{
"operation": "equals",
"field": "string",
"candidate_field": "string",
"index": "string",
"verification": "original_value",
"fallback_reason": "string"
}
]
},
"shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"join": {
"strategy_used": "broadcast",
"left_rows_scanned": 0,
"right_rows_scanned": 0,
"rows_matched": 0,
"rows_unmatched_left": 0,
"rows_unmatched_right": 0,
"duration_ms": 0
},
"reranker": {
"provider": "antfly",
"model": "string",
"documents_reranked": 0,
"duration_ms": 0
},
"merge": {
"strategy": "rrf",
"full_text_hits": 0,
"semantic_hits": 0,
"duration_ms": 0
},
"graph_metrics": [
{
"query_name": "string",
"source": "string",
"index_name": "string",
"metric_name": "string",
"freshness": "string",
"status": {
"state": "string",
"phase": "idle",
"edge_filter": {
"mode": "all",
"types": [
"string"
]
},
"metadata_version": 0,
"config_fingerprint": "string",
"maintenance_paused": true,
"build_queued": true,
"published_generation": 0,
"edge_generation": 0,
"target_edge_generation": 0,
"queued_generation": 0,
"building_generation": 0,
"build_job_id": 0,
"build_started_at_ms": 0,
"build_iteration": 0,
"build_lease_expires_at_ms": 0,
"build_worker_id": "string",
"build_cursor": "string",
"build_completed_units": 0,
"build_total_units": 0,
"build_pages": [
{
"phase": "string",
"iteration": 0,
"page_id": 0,
"state": "pending",
"range_kind": "full",
"worker_id": "string",
"lease_expires_at_ms": 0,
"attempt": 0,
"cursor": "string",
"completed_units": 0,
"total_units": 0,
"last_error": "string"
}
],
"build_pages_truncated": true,
"retry_count": 0,
"last_error": "string",
"progress": 0,
"converged": true,
"iterations_completed": 0,
"delta": 0,
"computed_at_ms": 0,
"last_event": {
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
},
"recent_events": [
{
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
}
]
}
}
],
"sort": {
"plan": "string",
"order_by": [
{
"field": "string",
"desc": true
}
],
"cursor": "string",
"exactness": "string",
"source": "string",
"candidate_source": "none",
"cursor_support": "string",
"source_load": "string",
"distributed_behavior": "string",
"selection_reason": "string",
"require_native": true,
"sort_lifecycle_state": "unsupported",
"index_sort_coverage": "string",
"candidate_count": 0,
"ordered_scanned_count": 0,
"cursor_rejected_count": 0,
"selected_count": 0,
"total_us": 0,
"distributed_shard_count": 0,
"budget_rejection_reason": "string",
"sort_rejection_reason": "string",
"sort_rejection_detail": "string",
"sort_rejection_field": "string"
}
},
"took": 0,
"status": 0,
"error": "string",
"table": "string"
}
]
}No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
No response body
Query an explicit namespace table
POST
/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/queryQueries a table through an explicit database and namespace route. While storage APIs are still bare-table-name based, the server fails closed when the resolved catalog table does not map to a unique physical table name.
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer YOUR_API_KEY
Request Body
Example:
{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
Code Examples
curl -X POST "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}'const response = await fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
});
const data = await response.json();fetch('/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
})
})
.then(response => response.json())
.then(data => console.log(data));import requests
headers = {
'Authorization': 'Bearer YOUR_API_KEY'
}
response = requests.post(
'/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query',
headers=headers,
json={
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}
)
data = response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
body := []byte(`{
"execution": {
"value_verification": {
"allow_scan": true,
"max_documents": 1,
"max_bytes": 1,
"max_regex_work": 1
}
},
"read_requirements": {
"visibility": "accepted",
"after_write": {
"table_id": 0,
"object_generation": 0,
"wal_lsn": 0
},
"wait_ms": 0
},
"remote_snapshot": "string",
"evaluate": {
"graph_query": "string",
"scope": "candidates",
"candidate_count": 1,
"max_rows": 1,
"compute": {},
"where": {},
"order_by": [
{
"expression": {
"literal": null,
"field": "string",
"ref": "string",
"call": "ai_decide",
"input": "...",
"decider": "string",
"questions": [
{}
],
"statement": "string",
"instructions": "string",
"criteria": {}
},
"descending": true
}
],
"aggregations": {}
},
"table_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"table": "wikipedia",
"query": {
"bool": {
"must": [
{
"match": {
"field": "body",
"text": "computer"
}
}
],
"filter": [
{
"term": {
"path": "/tenant",
"value": "acme"
}
}
],
"must_not": [
{
"exists": {
"path": "/deleted_at"
}
}
]
}
},
"full_text_search": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"full_text_index": "document_text",
"semantic_search": "artificial intelligence and machine learning applications",
"embedding_template": "{{remoteMedia url=this}}",
"indexes": [
"title_body_nomic",
"description_embedding"
],
"filter_prefix": "string",
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"exclusion_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"aggregations": {},
"embeddings": {},
"search_effort": 0.5,
"fields": [
"title",
"url",
"summary",
"created_at"
],
"hierarchy": null,
"highlight": {
"fields": [
"title",
"body"
],
"fragment_size": 16,
"max_fragments": 1
},
"limit": 20,
"offset": 0,
"timeout_ms": 5000,
"order_by": [
{
"field": "created_at",
"desc": true
},
{
"field": "score",
"desc": true
}
],
"search_after": [
null
],
"search_before": [
null
],
"distance_under": 0.5,
"distance_over": 0.1,
"merge_config": {
"strategy": "rrf",
"weights": {
"full_text": 0.3,
"title_embedding": 1
},
"window_size": 1,
"rank_constant": 0
},
"count": false,
"profile": false,
"reranker": {
"provider": "cohere",
"model": "rerank-v4.0-pro",
"field": "content"
},
"graph_metric": {
"direction": "out",
"name": "string",
"index": "string",
"metric": "string",
"top_k": 1,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0
},
"graph_metric_rerank": {
"direction": "out",
"index": "string",
"metric": "string",
"candidate_count": 1,
"base_weight": 0,
"weight": 0,
"missing_score": 0,
"metric_freshness": "published",
"seed_nodes": [
"string"
],
"damping": 0,
"auto_seed": true
},
"analyses": {
"pca": true,
"tsne": true
},
"graph_queries": {},
"document_renderer": "string",
"pruner": {
"min_score_ratio": 0.5,
"max_score_gap_percent": 30,
"min_absolute_score": 0.01,
"require_multi_index": true,
"std_dev_threshold": 1.5
},
"join": {
"right_target": {
"database": "string",
"namespace": "string",
"table": "string"
},
"right_table": "customers",
"join_type": "inner",
"on": {
"left_field": "customer_id",
"right_field": "id",
"operator": "eq"
},
"right_filters": {
"filter_query": {
"equals": "string",
"field": "string",
"case_sensitive": true,
"boost": 0
},
"filter_prefix": "string",
"limit": 0
},
"right_fields": [
"name",
"email",
"tier"
],
"strategy_hint": "broadcast",
"nested_join": "..."
},
"foreign_sources": {}
}`)
req, _ := http.NewRequest("POST", "/db/v1/databases/{databaseName}/namespaces/{namespaceName}/tables/{tableName}/query", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}Responses
{
"responses": [
{
"source_ranking": "rrf",
"next_source_cursor": "string",
"remote_snapshot": "string",
"evaluation": {},
"hits": {
"total": {
"value": 0,
"relation": "exact"
},
"hits": [
{
"_table": "string",
"_computed": {},
"_id": "string",
"_score": 0,
"_distance": 0,
"_index_scores": {},
"_score_details": {
"graph_metric_rerank": {
"index_name": "string",
"metric_name": "string",
"base_score": 0,
"base_weight": 0,
"metric_score": 0,
"metric_score_used": 0,
"metric_weight": 0,
"missing_score_used": true,
"final_score": 0,
"published_generation": 0
}
},
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"matched_artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
},
"evidence": {
"local_id": "string",
"decision": "string",
"confidence": 0,
"source_artifact": "string",
"source_artifact_key": "string",
"resolution_artifact": "string",
"resolution_artifact_key": "string",
"resolver": "string",
"resolver_table": "string",
"mention": {},
"canonical": {}
},
"matches": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
],
"position": "string",
"revision": "string",
"chunks": [
{
"_id": "string",
"_score": 0,
"_distance": 0,
"_source": {},
"hierarchy": {
"level": "source",
"parent_doc_key": "string",
"parent_unit_id": "string",
"artifact": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string",
"source": {
"name": "string",
"kind": "chunk",
"chunk_id": 0,
"unit_id": "string"
}
},
"ancestors": {
"source": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
},
"unit": {
"id": "string",
"document": {},
"key": "string",
"artifact_name": "string",
"source_field": "string",
"provenance": null
}
}
}
}
]
},
"_sort": [
null
],
"_highlights": {}
}
],
"max_score": 0
},
"aggregations": {},
"analyses": {},
"graph_metric_results": {},
"profile": {
"value_verification": {
"documents": 0,
"bytes": 0,
"verification_metrics_version": 0,
"source_read_us": 0,
"source_parse_us": 0,
"source_batches": 0,
"source_scalar_reads": 0,
"projected_sources": 0,
"stored_field_sources": 0,
"batch_refusals": 0,
"batch_peak_bytes": 0,
"plans": [
{
"operation": "equals",
"field": "string",
"candidate_field": "string",
"index": "string",
"verification": "original_value",
"fallback_reason": "string"
}
]
},
"shards": {
"total": 0,
"successful": 0,
"failed": 0
},
"join": {
"strategy_used": "broadcast",
"left_rows_scanned": 0,
"right_rows_scanned": 0,
"rows_matched": 0,
"rows_unmatched_left": 0,
"rows_unmatched_right": 0,
"duration_ms": 0
},
"reranker": {
"provider": "antfly",
"model": "string",
"documents_reranked": 0,
"duration_ms": 0
},
"merge": {
"strategy": "rrf",
"full_text_hits": 0,
"semantic_hits": 0,
"duration_ms": 0
},
"graph_metrics": [
{
"query_name": "string",
"source": "string",
"index_name": "string",
"metric_name": "string",
"freshness": "string",
"status": {
"state": "string",
"phase": "idle",
"edge_filter": {
"mode": "all",
"types": [
"string"
]
},
"metadata_version": 0,
"config_fingerprint": "string",
"maintenance_paused": true,
"build_queued": true,
"published_generation": 0,
"edge_generation": 0,
"target_edge_generation": 0,
"queued_generation": 0,
"building_generation": 0,
"build_job_id": 0,
"build_started_at_ms": 0,
"build_iteration": 0,
"build_lease_expires_at_ms": 0,
"build_worker_id": "string",
"build_cursor": "string",
"build_completed_units": 0,
"build_total_units": 0,
"build_pages": [
{
"phase": "string",
"iteration": 0,
"page_id": 0,
"state": "pending",
"range_kind": "full",
"worker_id": "string",
"lease_expires_at_ms": 0,
"attempt": 0,
"cursor": "string",
"completed_units": 0,
"total_units": 0,
"last_error": "string"
}
],
"build_pages_truncated": true,
"retry_count": 0,
"last_error": "string",
"progress": 0,
"converged": true,
"iterations_completed": 0,
"delta": 0,
"computed_at_ms": 0,
"last_event": {
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
},
"recent_events": [
{
"sequence": 0,
"kind": "publish",
"at_ms": 0,
"target_edge_generation": 0,
"published_generation": 0,
"score_count": 0
}
]
}
}
],
"sort": {
"plan": "string",
"order_by": [
{
"field": "string",
"desc": true
}
],
"cursor": "string",
"exactness": "string",
"source": "string",
"candidate_source": "none",
"cursor_support": "string",
"source_load": "string",
"distributed_behavior": "string",
"selection_reason": "string",
"require_native": true,
"sort_lifecycle_state": "unsupported",
"index_sort_coverage": "string",
"candidate_count": 0,
"ordered_scanned_count": 0,
"cursor_rejected_count": 0,
"selected_count": 0,
"total_us": 0,
"distributed_shard_count": 0,
"budget_rejection_reason": "string",
"sort_rejection_reason": "string",
"sort_rejection_detail": "string",
"sort_rejection_field": "string"
}
},
"took": 0,
"status": 0,
"error": "string",
"table": "string"
}
]
}No response body
No response body
No response body
No response body
No response body