# Vectors

## List Vectors

`vector_stores.vectors.list(strvector_store_name, VectorListParams**kwargs)  -> SyncCursorPageVectors[VectorDocument]`

**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.

### Parameters

- `vector_store_name: str`

  The name of the vector store

- `cursor: Optional[str]`

  Alias for starting_after. Use starting_after instead.

- `ending_before: Optional[str]`

- `filter: Optional[str]`

  Metadata filter expression (JSON)

- `include_vectors: Optional[bool]`

  Include embedding vectors

- `limit: Optional[int]`

- `sort_by: Optional[str]`

- `sort_order: Optional[SortOrder]`

  - `"asc"`

  - `"desc"`

- `starting_after: Optional[str]`

### Returns

- `class VectorDocument: …`

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

  - `id: str`

    Document ID

  - `content: Optional[TextContent]`

    Text content for documents.

    - `text: str`

      Text content to be embedded

    - `type: Optional[Literal["text"]]`

      Content type identifier

      - `"text"`

  - `metadata: Optional[Dict[str, object]]`

    Key-value metadata

  - `vector: Optional[List[float]]`

    Embedding vector (if requested)

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
page = client.vector_stores.vectors.list(
    vector_store_name="vector_store_name",
)
page = page.vectors[0]
print(page.id)
```

#### 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

`vector_stores.vectors.retrieve(strvector_id, VectorRetrieveParams**kwargs)  -> VectorDocument`

**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.

### Parameters

- `vector_store_name: str`

  The name of the vector store

- `vector_id: str`

  The ID of the vector to retrieve

- `include_vectors: Optional[bool]`

  Include embedding vectors

### Returns

- `class VectorDocument: …`

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

  - `id: str`

    Document ID

  - `content: Optional[TextContent]`

    Text content for documents.

    - `text: str`

      Text content to be embedded

    - `type: Optional[Literal["text"]]`

      Content type identifier

      - `"text"`

  - `metadata: Optional[Dict[str, object]]`

    Key-value metadata

  - `vector: Optional[List[float]]`

    Embedding vector (if requested)

### Example

```python
import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
vector_document = client.vector_stores.vectors.retrieve(
    vector_id="vector_id",
    vector_store_name="vector_store_name",
)
print(vector_document.id)
```

#### Response

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

## Domain Types

### Vector Document

- `class VectorDocument: …`

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

  - `id: str`

    Document ID

  - `content: Optional[TextContent]`

    Text content for documents.

    - `text: str`

      Text content to be embedded

    - `type: Optional[Literal["text"]]`

      Content type identifier

      - `"text"`

  - `metadata: Optional[Dict[str, object]]`

    Key-value metadata

  - `vector: Optional[List[float]]`

    Embedding vector (if requested)