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

32-byte encryption key as a hex string. Required for indexes created with the SDK-supplied KEK path; omit for KMS-backed indexes (the service resolves the key via the stored KMSBlob).

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 the stored rerank vector. Returned at the index’s configured storage_precision (float32 by default, or float16 if set at create time).

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) or wrong index_key on SDK-supplied indexes — see error model
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"
      }
    }
  ]
}

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

List IDs

⌘I

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

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