> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-fix-issues-on-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Vectors

> This endpoint queries a given vector over the existing vectors in the index.

## Request

<ParamField body="vector" name="vector" type="number[]" required>
  The query vector

  <Note>
    The provided vector should have the same number of dimensions as your
    index.
  </Note>
</ParamField>

<ParamField body="topK" type="number" required>
  The total number of the vectors that you want to receive as a query
  result. The response will be sorted based on the distance metric score,
  and `topK` vectors will be returned.
</ParamField>

<ParamField body="includeMetadata" type="boolean">
  Whether to include the metadata of the vectors in the response. Setting
  this `true` would be the best practice, since it will make it easier to
  identify the vectors.
</ParamField>

<ParamField body="includeVectors" type="boolean">
  Whether to include the vector data of the resulting vectors.
</ParamField>

## Response

<Note>
  The score is normalized to always be between 0 and 1. The closer the score is to 1, the more similar the vector is to the query vector.
  This does not depend on the distance metric you use.
</Note>

<ResponseField name="Response" type="Array">
  <Expandable defaultOpen="true">
    <ResponseField name="id" type="string" required>
      The ID of the resulting vector.
    </ResponseField>

    <ResponseField name="score" type="number" required>
      The score of the vector data, calculated based on the distance metric of your index.
    </ResponseField>

    <ResponseField name="vector" type="number[]" required>
      The resulting vector data.
    </ResponseField>

    <ResponseField name="metadata" type="Object">
      Whether to include the vector values of the resulting vector objects.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```sh curl
  curl https://better-dodo-20522-us1-vector.upstash.io/query \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -d '{ "vector": [0.42,0.63,0.05,0.72,0.83,0.49,0.6,0.48],
  		"topK": 2,
    		"includeVectors": true,
    		"includeMetadata": true
  	}'
  ```

  ```js Node
  const url = "https://better-dodo-20522-us1-vector.upstash.io/query"; // Replace with your index endpoint.
  const token = "YOUR_TOKEN"; // Replace with your actual token
  const data = {
    vector: [0.44, 0.8, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
    topK: 2,
    includeMetadata: true,
    includeVectors: true,
  };

  fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```

  ```python Python
  import requests
  import json

  url = 'https://better-dodo-20522-us1-vector.upstash.io/query' # Replace with your index endpoint.
  token = 'YOUR_TOKEN' # Replace with your actual token
  headers = {
      'Authorization': f'Bearer {token}',
      'Content-Type': 'application/json'
  }
  data = {
      'vector': [0.44, 0.8, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48],
      'topK': 2,
      includeMetadata: True,
      includeVectors: True
  }

  response = requests.post(url, headers=headers, data=json.dumps(data))
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK
  {
    "result" : [ 
  	{
  	    "id" : "id12",
  	    "score" : 1.0,
  	    "vector" : [ 0.42, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48 ],
  	    "metadata" : {"key":"value"}
    	}, 
  	{
  	    "id" : "id11",
  	    "score" : 0.99996454,
  	    "vector" : [ 0.44, 0.63, 0.05, 0.72, 0.83, 0.49, 0.6, 0.48 ],
  	    "metadata" : {"key":"value"}
    	} 
    ]
  }
  ```
</ResponseExample>