Get Vectors

POST

vectors

get

Get Vectors

curl --request POST \
  --url https://api.example.com/v1/vectors/get

import requests

url = "https://api.example.com/v1/vectors/get"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/vectors/get', 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.example.com/v1/vectors/get",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/v1/vectors/get"

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

	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.example.com/v1/vectors/get")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/vectors/get")

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

request = Net::HTTP::Post.new(url)

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

Retrieve specific vectors from the index by their IDs.

Authentication

Required - API key via X-API-Key header:

X-API-Key: cyborg_your_api_key_here

You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.

Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "ids": ["item_1", "item_2", "item_3"],
  "include": ["vector", "contents", "metadata"]
}

Show parameters

index_name

string

required

Name of the target index

index_key

string

required

32-byte encryption key as hex string

ids

array[string]

required

List of item IDs to retrieve

include

array[string]

default:["vector","contents","metadata"]

Fields to include in response:

Show include options

vector

string

Include original vector (only for IVFFlat indexes)

contents

string

Include text content associated with the vector

metadata

string

Include item metadata key-value pairs

Response

{
  "results": [
    {
      "id": "item_1",
      "vector": [0.1, 0.2, 0.3, 0.4],
      "contents": "Hello world!",
      "metadata": {"category": "greeting", "language": "en"}
    },
    {
      "id": "item_2",
      "vector": [0.5, 0.6, 0.7, 0.8],
      "contents": "Bonjour monde!",
      "metadata": {"category": "greeting", "language": "fr"}
    }
  ]
}

If an item ID doesn’t exist, it will be omitted from the results.

Exceptions

401: Authentication failed (invalid API key)
404: Index not found
422: Invalid request parameters
500: Internal server error

Example Usage

Get All Fields:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": ["item_1", "item_2", "item_3"]
     }'

Get Only Contents:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": ["doc_1", "doc_2", "doc_3"],
       "include": ["contents"]
     }'

Get Metadata Only:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": ["user_1", "user_2"],
       "include": ["metadata"]
     }'

Batch Retrieval:

curl -X POST "http://localhost:8000/v1/vectors/get" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "ids": [
         "batch_1", "batch_2", "batch_3", "batch_4", "batch_5",
         "batch_6", "batch_7", "batch_8", "batch_9", "batch_10"
       ],
       "include": ["contents", "metadata"]
     }'

Example Response (Contents Only):

{
  "results": [
    {
      "id": "doc_1",
      "contents": "First document content here..."
    },
    {
      "id": "doc_2",
      "contents": "Second document content here..."
    },
    {
      "id": "doc_3",
      "contents": "Third document content here..."
    }
  ]
}

Example Response (Metadata Only):

{
  "results": [
    {
      "id": "user_1",
      "metadata": {
        "name": "Alice Smith",
        "role": "admin",
        "department": "engineering",
        "created": "2024-01-01"
      }
    },
    {
      "id": "user_2",
      "metadata": {
        "name": "Bob Johnson",
        "role": "user",
        "department": "marketing",
        "created": "2024-01-02"
      }
    }
  ]
}

For IVF and IVFPQ index types, the vector field cannot be included in the response as these index types use compression techniques that don’t preserve original vectors.

Use Cases

Content retrieval: Get original text content by ID
Metadata lookup: Retrieve item metadata for display
Data validation: Verify stored data integrity
Bulk operations: Retrieve multiple items efficiently
Content management: Extract specific items for editing or processing

Train Index

Delete Vectors

⌘I

Introduction

Client

Encrypted Index

Types & Getters

Authentication

Request Body

Response

Exceptions

Example Usage

Use Cases

​Authentication

​Request Body

​Response

​Exceptions

​Example Usage

​Use Cases

Authentication

Request Body

Response

Exceptions

Example Usage

Use Cases