# Vectors

## List Vectors

**get** `/v5/vector-stores/{vector_store_name}/vectors`

List documents in a vector store with cursor-based pagination.

**Use Cases:** Browse documents, export content, audit stored data, or retrieve documents by metadata
without semantic search.

**Ordering:** Documents are returned in storage order (insertion order), not ranked by similarity.
For similarity-based retrieval, use the query endpoint.

**Filtering:** Apply metadata filters to narrow results to specific subsets (e.g., all documents
where `category: "research"`). Only indexed fields can be used for filtering.

**Pagination:** Uses cursor-based pagination for efficient traversal of large datasets. Pass the
`next_cursor` from each response as `starting_after` to retrieve the next page, or `prev_cursor`
as `ending_before` to retrieve the previous page. A null cursor indicates no further pages exist.

**Embedding Vectors:** Setting `include_vectors=true` includes the full embedding vector arrays in
the response. This significantly increases payload size and reduces the maximum page size from 1000 to
100 documents. Enable only when raw vectors are required for external processing.

### Path Parameters

- `vector_store_name: string`

  The name of the vector store

### Query Parameters

- `cursor: optional string`

  Alias for starting_after. Use starting_after instead.

- `ending_before: optional string`

- `filter: optional string`

  Metadata filter expression (JSON)

- `include_vectors: optional boolean`

  Include embedding vectors

- `limit: optional number`

- `sort_by: optional string`

- `sort_order: optional SortOrder`

  - `"asc"`

  - `"desc"`

- `starting_after: optional string`

### Returns

- `has_more: boolean`

  Whether there are more items left to be fetched.

- `items: array of VectorDocument`

  Array of documents

  - `id: string`

    Document ID

  - `content: optional TextContent`

    Text content for documents.

    - `text: string`

      Text content to be embedded

    - `type: optional "text"`

      Content type identifier

      - `"text"`

  - `metadata: optional map[unknown]`

    Key-value metadata

  - `vector: optional array of number`

    Embedding vector (if requested)

- `total: number`

  The total of items that match the query. This is greater than or equal to the number of items returned.

- `vectors: array of VectorDocument`

  Array of documents. Deprecated: use `items` instead.

  - `id: string`

    Document ID

  - `content: optional TextContent`

    Text content for documents.

  - `metadata: optional map[unknown]`

    Key-value metadata

  - `vector: optional array of number`

    Embedding vector (if requested)

- `limit: optional number`

  The maximum number of items to return.

- `next_cursor: optional string`

  Pass as starting_after to fetch the next page. None when there is no next page.

- `object: optional "list"`

  - `"list"`

- `prev_cursor: optional string`

  Pass as ending_before to fetch the previous page. None when on the first page.

### Example

```http
curl https://api.egp.scale.com/v5/vector-stores/$VECTOR_STORE_NAME/vectors \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "content": {
        "text": "text",
        "type": "text"
      },
      "metadata": {
        "foo": "bar"
      },
      "vector": [
        0
      ]
    }
  ],
  "total": 0,
  "vectors": [
    {
      "id": "id",
      "content": {
        "text": "text",
        "type": "text"
      },
      "metadata": {
        "foo": "bar"
      },
      "vector": [
        0
      ]
    }
  ],
  "limit": 0,
  "next_cursor": "next_cursor",
  "object": "list",
  "prev_cursor": "prev_cursor"
}
```

## Get Vector

**get** `/v5/vector-stores/{vector_store_name}/vectors/{vector_id}`

Retrieve a single document by its unique ID.

Returns the document's full content, metadata, and optionally its embedding vector. Use this endpoint
for direct lookups when the exact document ID is known. For content similarity search,
use the query endpoint.

### Path Parameters

- `vector_store_name: string`

  The name of the vector store

- `vector_id: string`

  The ID of the vector to retrieve

### Query Parameters

- `include_vectors: optional boolean`

  Include embedding vectors

### Returns

- `VectorDocument object { id, content, metadata, vector }`

  A document returned from direct lookups (get/list operations).

  - `id: string`

    Document ID

  - `content: optional TextContent`

    Text content for documents.

    - `text: string`

      Text content to be embedded

    - `type: optional "text"`

      Content type identifier

      - `"text"`

  - `metadata: optional map[unknown]`

    Key-value metadata

  - `vector: optional array of number`

    Embedding vector (if requested)

### Example

```http
curl https://api.egp.scale.com/v5/vector-stores/$VECTOR_STORE_NAME/vectors/$VECTOR_ID \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "content": {
    "text": "text",
    "type": "text"
  },
  "metadata": {
    "foo": "bar"
  },
  "vector": [
    0
  ]
}
```

## Domain Types

### Vector Document

- `VectorDocument object { id, content, metadata, vector }`

  A document returned from direct lookups (get/list operations).

  - `id: string`

    Document ID

  - `content: optional TextContent`

    Text content for documents.

    - `text: string`

      Text content to be embedded

    - `type: optional "text"`

      Content type identifier

      - `"text"`

  - `metadata: optional map[unknown]`

    Key-value metadata

  - `vector: optional array of number`

    Embedding vector (if requested)