> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vectoraidb.actian.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search vectors

> Find the most similar vectors in a collection using approximate nearest neighbor search. Supports score thresholds, payload filtering, and tunable HNSW parameters.



## OpenAPI

````yaml post /collections/{collection_name}/points/search
openapi: 3.0.3
info:
  title: Actian VectorAI DB - Search API
  description: Vector similarity search operations for Actian VectorAI DB.
  version: 1.0.0
  contact:
    name: Actian Corporation
    url: https://www.actian.com
servers:
  - url: http://localhost:6573
    description: Local development server (REST API)
  - url: https://api.vectorai.actian.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Vector similarity search operations
  - name: Scroll
    description: Pagination and iteration
  - name: Count
    description: Counting operations
paths:
  /collections/{collection_name}/points/search:
    post:
      tags:
        - Search
      summary: Search vectors
      description: >-
        Find the most similar vectors in a collection using approximate nearest
        neighbor search. Supports score thresholds, payload filtering, and
        tunable HNSW parameters.
      operationId: search_points
      parameters:
        - name: collection_name
          in: path
          required: true
          schema:
            type: string
          description: The name of the collection to search.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vector
              properties:
                vector:
                  type: array
                  items:
                    type: number
                  example:
                    - 0.1
                    - 0.2
                    - 0.3
                    - 0.4
                  description: >-
                    The query vector to search for. The number of dimensions
                    must match the collection's configured vector size.
                limit:
                  type: integer
                  default: 10
                  example: 5
                  description: Maximum number of results to return. Defaults to 10.
                offset:
                  type: integer
                  default: 0
                  example: 0
                  description: >-
                    Number of results to skip for pagination. Use with `limit`
                    to page through results.
                score_threshold:
                  type: number
                  example: 0.7
                  description: >-
                    Minimum similarity score for results. Only points with
                    scores at or above this threshold are returned.
                filter:
                  type: object
                  description: >-
                    Optional filter to narrow search results based on payload
                    metadata. See the Filters API for syntax.
                with_payload:
                  type: boolean
                  default: true
                  example: true
                  description: Whether to include payload metadata in the response.
                with_vector:
                  type: boolean
                  default: false
                  example: false
                  description: >-
                    Whether to include vector data in the response. Set to
                    `false` to reduce response size.
                params:
                  type: object
                  description: >-
                    Advanced search parameters for tuning search quality and
                    performance.
                  properties:
                    hnsw_ef:
                      type: integer
                      example: 128
                      description: >-
                        Controls the number of candidates HNSW evaluates during
                        search. Higher values improve accuracy at the cost of
                        latency.
                    exact:
                      type: boolean
                      example: false
                      description: >-
                        If `true`, performs an exact brute-force search instead
                        of approximate. Slower but guarantees finding true
                        nearest neighbors.
            examples:
              basic_search:
                summary: Basic search
                value:
                  vector:
                    - 0.1
                    - 0.2
                    - 0.3
                    - 0.4
                  limit: 5
                  offset: 0
                  with_payload: true
                  with_vector: false
              search_with_threshold:
                summary: With score threshold
                value:
                  vector:
                    - 0.1
                    - 0.2
                    - 0.3
                    - 0.4
                  limit: 10
                  offset: 0
                  score_threshold: 0.7
                  with_payload: true
                  with_vector: false
                  params:
                    hnsw_ef: 128
                    exact: false
              search_with_filter:
                summary: With payload filter
                value:
                  vector:
                    - 0.1
                    - 0.2
                    - 0.3
                    - 0.4
                  limit: 10
                  offset: 0
                  filter:
                    must:
                      - key: category
                        match:
                          value: electronics
                  with_payload: true
                  with_vector: false
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    type: object
                    properties:
                      hardware:
                        type: object
                        nullable: true
                        description: >-
                          Hardware resource counters for the operation,
                          including CPU, payload I/O, payload index I/O, and
                          vector I/O metrics.
                  time:
                    type: number
                    format: double
                    example: 0.0000553
                    description: Time spent to process this request, in seconds.
                  status:
                    type: string
                    example: ok
                    description: Operation status.
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          oneOf:
                            - type: integer
                            - type: string
                          example: 1
                          description: The point's unique identifier.
                        version:
                          type: integer
                          example: 0
                          description: The point's version number.
                        score:
                          type: number
                          example: 0.9843740463256836
                          description: >-
                            Similarity score between the query vector and this
                            point.
                        payload:
                          type: object
                          nullable: true
                          example: null
                          description: >-
                            Payload metadata, or null if `with_payload` is
                            false.
                        vector:
                          type: array
                          nullable: true
                          items:
                            type: number
                          example: null
                          description: Vector data, or null if `with_vector` is false.
              example:
                usage:
                  hardware: null
                time: 0.0000553
                status: ok
                result:
                  - id: 1
                    version: 0
                    score: 1
                    payload: null
                    vector: null
                  - id: 3
                    version: 0
                    score: 0.9843740463256836
                    payload: null
                    vector: null
                  - id: 2
                    version: 0
                    score: 0.9688639640808105
                    payload: null
                    vector: null
        4XX:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: Python
          label: Basic search
          source: |
            from actian_vectorai_client import VectorAIClient
            import random

            with VectorAIClient("localhost:6574") as client:
                # Basic vector search
                query = [random.gauss(0, 1) for _ in range(64)]
                results = client.points.search("my_collection", vector=query, limit=5)
                
                for r in results:
                    print(f"ID: {r.id}, Score: {r.score:.4f}")
                    print(f"Payload: {r.payload.get('category')}")
        - lang: Python
          label: Search with score threshold
          source: |
            from actian_vectorai_client import VectorAIClient
            import random

            with VectorAIClient("localhost:6574") as client:
                # Search with minimum score
                query = [random.gauss(0, 1) for _ in range(64)]
                results = client.points.search(
                    "my_collection",
                    vector=query,
                    limit=10,
                    score_threshold=0.7
                )
                print(f"Found {len(results)} results above threshold")
        - lang: Python
          label: Search with custom HNSW
          source: |
            from actian_vectorai_client import VectorAIClient, SearchParams
            import random

            with VectorAIClient("localhost:6574") as client:
                # Search with custom HNSW parameters
                query = [random.gauss(0, 1) for _ in range(64)]
                results = client.points.search(
                    "my_collection",
                    vector=query,
                    limit=5,
                    params=SearchParams(hnsw_ef=256, exact=False)
                )
                print(f"Found {len(results)} results")
        - lang: Python
          label: Exact search
          source: |
            from actian_vectorai_client import VectorAIClient, SearchParams
            import random

            with VectorAIClient("localhost:6574") as client:
                # Exact (brute-force) search
                query = [random.gauss(0, 1) for _ in range(64)]
                results = client.points.search(
                    "my_collection",
                    vector=query,
                    limit=5,
                    params=SearchParams(exact=True)
                )
                for r in results:
                    print(f"ID: {r.id}, Score: {r.score:.4f}")
        - lang: JavaScript
          label: Basic search
          source: >
            import { VectorAIClient } from '@actian/vectorai-client';


            const client = new VectorAIClient('localhost:6574');


            const results = await client.points.search('my_collection', [0.1,
            0.2, 0.3, 0.4], {
                limit: 5,
                withPayload: true,
            });

            for (const r of results) {
                console.log(`id=${r.id}  score=${r.score.toFixed(4)}  payload=${JSON.stringify(r.payload)}`);
            }


            client.close();
        - lang: JavaScript
          label: Filtered search
          source: >
            import { VectorAIClient, Field } from '@actian/vectorai-client';


            const client = new VectorAIClient('localhost:6574');


            const filter = Field.of('category').eq('electronics');

            const results = await client.points.search('my_collection', [0.1,
            0.2, 0.3, 0.4], {
                limit: 5,
                filter,
                withPayload: true,
            });

            console.log(`Found ${results.length} results`);


            client.close();
        - lang: cURL
          label: Search
          source: >
            curl -X POST
            "http://localhost:6573/collections/my_collection/points/search" \
              -H "Content-Type: application/json" \
              -H 'Authorization: Bearer <admin-jwt-or-access-token>' \
              -d '{
                "vector": [0.1, 0.2, 0.3, 0.4],
                "limit": 5
              }'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: object
          properties:
            error:
              type: string
        time:
          type: number
          format: double
          description: Time spent to process this request, in seconds.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Admin JWT or access token for authenticating requests to VectorAI DB.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.