Query Vectors

curl --request POST \
  --url https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "content": {
    "text": "<string>",
    "type": "text"
  },
  "query_type": "semantic",
  "top_k": 10,
  "filter": {},
  "rerank_config": {
    "type": "base",
    "model": "<string>",
    "top_n": 2,
    "instruction": "<string>"
  },
  "rerank": false,
  "rerank_model": "<string>",
  "rerank_top_n": 2,
  "rerank_instruction": "<string>",
  "include_vectors": false
}
'

import requests

url = "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query"

payload = {
    "content": {
        "text": "<string>",
        "type": "text"
    },
    "query_type": "semantic",
    "top_k": 10,
    "filter": {},
    "rerank_config": {
        "type": "base",
        "model": "<string>",
        "top_n": 2,
        "instruction": "<string>"
    },
    "rerank": False,
    "rerank_model": "<string>",
    "rerank_top_n": 2,
    "rerank_instruction": "<string>",
    "include_vectors": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    content: {text: '<string>', type: 'text'},
    query_type: 'semantic',
    top_k: 10,
    filter: {},
    rerank_config: {type: 'base', model: '<string>', top_n: 2, instruction: '<string>'},
    rerank: false,
    rerank_model: '<string>',
    rerank_top_n: 2,
    rerank_instruction: '<string>',
    include_vectors: false
  })
};

fetch('https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content' => [
        'text' => '<string>',
        'type' => 'text'
    ],
    'query_type' => 'semantic',
    'top_k' => 10,
    'filter' => [
        
    ],
    'rerank_config' => [
        'type' => 'base',
        'model' => '<string>',
        'top_n' => 2,
        'instruction' => '<string>'
    ],
    'rerank' => false,
    'rerank_model' => '<string>',
    'rerank_top_n' => 2,
    'rerank_instruction' => '<string>',
    'include_vectors' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query"

	payload := strings.NewReader("{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}"

response = http.request(request)
puts response.read_body

{
  "vectors": [
    {
      "id": "<string>",
      "score": 123,
      "content": {
        "text": "<string>",
        "type": "text"
      },
      "metadata": {},
      "vector": [
        123
      ]
    }
  ],
  "metadata": {
    "search_type": "<string>",
    "total_query_time_ms": 123,
    "embedding_config": {
      "type": "<string>",
      "model_deployment_id": "<string>"
    },
    "embedding_time_ms": 123,
    "index_query_time_ms": 123,
    "reranking_model": "<string>",
    "reranking_time_ms": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Vector Stores

Query Vectors

Query documents using similarity search with optional reranking.

Primary endpoint for semantic search, question-answering, and RAG (Retrieval-Augmented Generation) applications. Returns documents ranked by relevance to the query text with similarity scores.

Query Types:

semantic (default): Approximate nearest-neighbor search using HNSW over cosine similarity of document embeddings. Optimal for question-answering, conceptual search, and finding semantically related content without requiring exact keyword matches.
lexical: Keyword-based text search (BM25 algorithm). Optimal for exact phrase matching, proper nouns, and scenarios where keyword presence is more important than semantic similarity.
hybrid: Combines semantic and lexical approaches with weighted scoring. Provides maximum recall by identifying documents matching either semantically or lexically.

Metadata Filtering: Narrow the search scope by applying metadata filters (e.g., search only documents where category: "technical"). Only indexed fields can be used for filtering. Filters are applied before similarity search for optimal efficiency.

Reranking (Advanced): Optionally enhance result quality using a cross-encoder reranking model. The reranker rescores the initial results using a more sophisticated model that evaluates the complete query-document pair (not solely embeddings). This adds 100-500ms latency but significantly improves precision for high-stakes applications.

Reranking Strategy: Set top_k higher than the desired final count (e.g., 50) to retrieve more candidates from the initial search. Then configure rerank_top_n to the desired final count (e.g., 10) to return only the most relevant documents after reranking. This two-stage approach maximizes both recall and precision.

Performance Metrics: The response includes detailed timing breakdowns (embedding generation time, index query time, reranking time) to facilitate search pipeline optimization and latency analysis.

Similarity Scores: Each result includes a score field indicating relevance. Higher scores indicate greater relevance. Score ranges and semantics vary by query type (semantic scores use cosine similarity, lexical scores use BM25, hybrid scores combine both approaches).

POST

vector-stores

{vector_store_name}

query

Query Vectors

curl --request POST \
  --url https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "content": {
    "text": "<string>",
    "type": "text"
  },
  "query_type": "semantic",
  "top_k": 10,
  "filter": {},
  "rerank_config": {
    "type": "base",
    "model": "<string>",
    "top_n": 2,
    "instruction": "<string>"
  },
  "rerank": false,
  "rerank_model": "<string>",
  "rerank_top_n": 2,
  "rerank_instruction": "<string>",
  "include_vectors": false
}
'

import requests

url = "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query"

payload = {
    "content": {
        "text": "<string>",
        "type": "text"
    },
    "query_type": "semantic",
    "top_k": 10,
    "filter": {},
    "rerank_config": {
        "type": "base",
        "model": "<string>",
        "top_n": 2,
        "instruction": "<string>"
    },
    "rerank": False,
    "rerank_model": "<string>",
    "rerank_top_n": 2,
    "rerank_instruction": "<string>",
    "include_vectors": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    content: {text: '<string>', type: 'text'},
    query_type: 'semantic',
    top_k: 10,
    filter: {},
    rerank_config: {type: 'base', model: '<string>', top_n: 2, instruction: '<string>'},
    rerank: false,
    rerank_model: '<string>',
    rerank_top_n: 2,
    rerank_instruction: '<string>',
    include_vectors: false
  })
};

fetch('https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content' => [
        'text' => '<string>',
        'type' => 'text'
    ],
    'query_type' => 'semantic',
    'top_k' => 10,
    'filter' => [
        
    ],
    'rerank_config' => [
        'type' => 'base',
        'model' => '<string>',
        'top_n' => 2,
        'instruction' => '<string>'
    ],
    'rerank' => false,
    'rerank_model' => '<string>',
    'rerank_top_n' => 2,
    'rerank_instruction' => '<string>',
    'include_vectors' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query"

	payload := strings.NewReader("{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.egp.scale.com/v5/vector-stores/{vector_store_name}/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": {\n    \"text\": \"<string>\",\n    \"type\": \"text\"\n  },\n  \"query_type\": \"semantic\",\n  \"top_k\": 10,\n  \"filter\": {},\n  \"rerank_config\": {\n    \"type\": \"base\",\n    \"model\": \"<string>\",\n    \"top_n\": 2,\n    \"instruction\": \"<string>\"\n  },\n  \"rerank\": false,\n  \"rerank_model\": \"<string>\",\n  \"rerank_top_n\": 2,\n  \"rerank_instruction\": \"<string>\",\n  \"include_vectors\": false\n}"

response = http.request(request)
puts response.read_body

{
  "vectors": [
    {
      "id": "<string>",
      "score": 123,
      "content": {
        "text": "<string>",
        "type": "text"
      },
      "metadata": {},
      "vector": [
        123
      ]
    }
  ],
  "metadata": {
    "search_type": "<string>",
    "total_query_time_ms": 123,
    "embedding_config": {
      "type": "<string>",
      "model_deployment_id": "<string>"
    },
    "embedding_time_ms": 123,
    "index_query_time_ms": 123,
    "reranking_model": "<string>",
    "reranking_time_ms": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

x-api-key

string

header

required

Headers

x-selected-account-id

string | null

Path Parameters

vector_store_name

string

required

The name of the vector store

Body

application/json

Request to query documents.

content

Content · object

required

Query content for automatic embedding

Show child attributes

query_type

enum<string>

default:semantic

Query type: semantic, lexical, or hybrid

Available options:

semantic,

lexical,

hybrid

top_k

integer

default:10

Number of search results to return

Required range: x >= 1

filter

Filter · object

Metadata filter expression

rerank_config

RerankConfig · object

Reranking configuration. Presence enables reranking; omit to disable. Pass an empty object ({}) to enable reranking with system defaults.

Show child attributes

rerank

boolean

default:false

[Deprecated: use rerank_config] Enable reranking of search results

rerank_model

string

[Deprecated: use rerank_config.model] Reranking model to use

rerank_top_n

integer

[Deprecated: use rerank_config.top_n] Number of results after reranking

Required range: x >= 1

rerank_instruction

string

[Deprecated: use rerank_config.instruction] Custom instruction for reranker

include_vectors

boolean

default:false

Include embedding vectors in response

Response

Successful Response

Response for query operation.

vectors

QueryVectorDocumentResponse · object[]

required

Array of matching documents

Show child attributes

metadata

QueryMetadata · object

required

Query execution metadata

Show child attributes

Count Vectors List Files

⌘I