Skip to main content

Query Datasets

POST /v1/query
Request:
{
  "query": "machine learning transformers",
  "dataset_ids": ["uuid-1", "uuid-2"],
  "top_k": 10,
  "filters": {
    "uuid-1": {"year": {"$gte": 2023}},
    "uuid-2": {"category": {"$eq": "research"}}
  }
}
Fields:
FieldTypeRequiredDescription
querystringOne of query/vectorNatural language search text
vectornumber[]One of query/vectorPre-computed embedding
dataset_idsstring[]YesDataset IDs to search
top_knumberNo (default 10)Max results (max 100)
filtersobjectNoPer-dataset metadata filters
Response:
{
  "query_id": "uuid",
  "results": [
    {
      "dataset_id": "uuid-1",
      "id": "vec-123",
      "score": 0.95,
      "metadata": {
        "title": "Attention Is All You Need",
        "year": 2017,
        "text": "We propose a new simple network architecture..."
      },
      "embedding_model": "text-embedding-3-small"
    }
  ],
  "warnings": []
}
Result fields:
FieldTypeDescription
dataset_idstringSource dataset
idstringVector ID in the seller’s DB
scorenumberRelevance score (higher = better)
metadataobjectKey-value pairs from the seller’s vector DB
embedding_modelstringOnly in multi-model queries
Status codes:
  • 200 — success
  • 400 — validation error (bad filters, missing fields, dimension mismatch)
  • 402 — insufficient balance (includes balance and estimated_cost)
  • 403 — no access to one or more datasets