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

# Search

> Search for nodes in the graph database.

This endpoint performs semantic search across the knowledge graph to find
relevant nodes based on the provided query. It supports different search
types and can be scoped to specific datasets.

## Request Parameters
- **search_type** (SearchType): Type of search to perform (default: HYBRID_COMPLETION). Use AGENTIC_COMPLETION to enable skills, tools and max_iter.
- **datasets** (Optional[List[str]]): List of dataset names to search within
- **dataset_ids** (Optional[List[UUID]]): List of dataset UUIDs to search within
- **query** (str): The search query string
- **system_prompt** Optional[str]: System prompt to be used for Completion type searches in Cognee
- **node_name** Optional[list[str]]: Filter results to specific node_sets defined in the add pipeline (for targeted search).
- **top_k** (Optional[int]): Maximum number of results to return (default: 15)
- **only_context** bool: Set to true to only return context Cognee will be sending to LLM in Completion type searches. This will be returned instead of LLM calls for completion type searches.
- **verbose** (bool): Return detailed result information including the graph representation when available (default: false)
- **skills** (Optional[List[str]]): Skill names to load into the agentic retriever (AGENTIC_COMPLETION only)
- **tools** (Optional[List[str]]): Tool whitelist for AGENTIC_COMPLETION searches
- **max_iter** (Optional[int]): Max agentic iterations, must be >= 1 (AGENTIC_COMPLETION only)
- **include_references** (bool): Attach source references to completion-type results (default: true)
- **code_query** (Optional[dict]): Structured operation arguments for CODE search

## Response
Returns a list of search results containing relevant nodes from the graph.

## Error Codes
- **402/403/404/409/422**: Cognee errors (payment required, permission
  denied, missing user, session-dataset conflict, prerequisites not met)
  return their own status code and message via the global error handler
- **500 Internal Server Error**: Unexpected error during search

## Notes
- Datasets sent by name will only map to datasets owned by the request sender
- To search datasets not owned by the request sender, dataset UUID is needed
- If dataset_ids is provided, the datasets name list is ignored



## OpenAPI

````yaml /cognee_openapi_spec.json post /api/v1/search
openapi: 3.1.0
info:
  title: Cognee API
  description: Cognee API with Bearer token and Cookie auth
  version: 1.0.0
servers:
  - url: https://api.cognee.ai
    description: Production server (full functionality)
  - url: http://localhost:8000
    description: Local development server (requires local setup)
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: activity
    description: ''
  - name: add
    description: Data ingestion endpoints for adding text, files, and structured data.
  - name: agent connections
    description: ''
  - name: agent management
    description: ''
  - name: auth
    description: >-
      Authentication endpoints for user registration, login, and token
      management.
  - name: checks
    description: ''
  - name: cognify
    description: >-
      Knowledge processing endpoints to transform raw data into knowledge
      graphs.
  - name: configuration
    description: ''
  - name: datasets
    description: Dataset management endpoints for listing, creating, and deleting datasets.
  - name: delete
    description: Data deletion endpoints (deprecated — use datasets endpoints instead).
  - name: forget
    description: ''
  - name: health
    description: ''
  - name: improve
    description: ''
  - name: integrations
    description: ''
  - name: llm
    description: ''
  - name: memify
    description: ''
  - name: ontologies
    description: ''
  - name: permissions
    description: Permission management for multi-user access control.
  - name: recall
    description: ''
  - name: remember
    description: ''
  - name: responses
    description: Response generation endpoints using the knowledge graph.
  - name: schema
    description: ''
  - name: search
    description: Search endpoints for querying the knowledge graph.
  - name: sessions
    description: ''
  - name: settings
    description: Configuration endpoints for managing Cognee settings.
  - name: skills
    description: ''
  - name: slack
    description: ''
  - name: sync
    description: ''
  - name: update
    description: ''
  - name: users
    description: User management endpoints.
  - name: validate
    description: ''
  - name: visualize
    description: Graph visualization endpoints.
paths:
  /api/v1/search:
    post:
      tags:
        - search
      summary: Search
      description: >-
        Search for nodes in the graph database.


        This endpoint performs semantic search across the knowledge graph to
        find

        relevant nodes based on the provided query. It supports different search

        types and can be scoped to specific datasets.


        ## Request Parameters

        - **search_type** (SearchType): Type of search to perform (default:
        HYBRID_COMPLETION). Use AGENTIC_COMPLETION to enable skills, tools and
        max_iter.

        - **datasets** (Optional[List[str]]): List of dataset names to search
        within

        - **dataset_ids** (Optional[List[UUID]]): List of dataset UUIDs to
        search within

        - **query** (str): The search query string

        - **system_prompt** Optional[str]: System prompt to be used for
        Completion type searches in Cognee

        - **node_name** Optional[list[str]]: Filter results to specific
        node_sets defined in the add pipeline (for targeted search).

        - **top_k** (Optional[int]): Maximum number of results to return
        (default: 15)

        - **only_context** bool: Set to true to only return context Cognee will
        be sending to LLM in Completion type searches. This will be returned
        instead of LLM calls for completion type searches.

        - **verbose** (bool): Return detailed result information including the
        graph representation when available (default: false)

        - **skills** (Optional[List[str]]): Skill names to load into the agentic
        retriever (AGENTIC_COMPLETION only)

        - **tools** (Optional[List[str]]): Tool whitelist for AGENTIC_COMPLETION
        searches

        - **max_iter** (Optional[int]): Max agentic iterations, must be >= 1
        (AGENTIC_COMPLETION only)

        - **include_references** (bool): Attach source references to
        completion-type results (default: true)

        - **code_query** (Optional[dict]): Structured operation arguments for
        CODE search


        ## Response

        Returns a list of search results containing relevant nodes from the
        graph.


        ## Error Codes

        - **402/403/404/409/422**: Cognee errors (payment required, permission
          denied, missing user, session-dataset conflict, prerequisites not met)
          return their own status code and message via the global error handler
        - **500 Internal Server Error**: Unexpected error during search


        ## Notes

        - Datasets sent by name will only map to datasets owned by the request
        sender

        - To search datasets not owned by the request sender, dataset UUID is
        needed

        - If dataset_ids is provided, the datasets name list is ignored
      operationId: search_api_v1_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPayloadDTO'
            example:
              search_type: GRAPH_COMPLETION
              query: What is Cognee?
              top_k: 10
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - items:
                      $ref: '#/components/schemas/SearchResult'
                    type: array
                  - items: {}
                    type: array
                title: Response Search Api V1 Search Post
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse'
          description: Internal Server Error
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
components:
  schemas:
    SearchPayloadDTO:
      properties:
        searchType:
          $ref: '#/components/schemas/SearchType'
          description: >-
            Retrieval strategy. Common values: HYBRID_COMPLETION (default,
            passages + entities + LLM answer), GRAPH_COMPLETION (graph context +
            LLM answer), CODE (deterministic code graph), RAG_COMPLETION,
            CHUNKS, SUMMARIES, TEMPORAL, FEELING_LUCKY (auto-select),
            AGENTIC_COMPLETION (enables skills/tools/max_iter).
          default: HYBRID_COMPLETION
        datasets:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Datasets
          description: >-
            Dataset names to search. Names only resolve to datasets owned by the
            caller; use dataset_ids for datasets shared with you.
          examples:
            - - default_dataset
        datasetIds:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Datasetids
          description: >-
            Dataset UUIDs to search (required for datasets shared with you).
            When provided, the datasets name list is ignored.
          examples:
            - null
        query:
          type: string
          title: Query
          default: What is in the document?
        systemPrompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Systemprompt
          default: >-
            Answer the question using the provided context. Be as brief as
            possible.
        nodeName:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Nodename
          description: >-
            Restrict results to nodes in these node_sets (the node_set values
            used during add/remember).
          examples:
            - null
        topK:
          anyOf:
            - type: integer
            - type: 'null'
          title: Topk
          default: 15
        onlyContext:
          type: boolean
          title: Onlycontext
          default: false
        verbose:
          type: boolean
          title: Verbose
          description: >-
            Return detailed result information including the graph
            representation when available.
          default: false
        skills:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Skills
          description: >-
            Skill names to load into the agentic retriever. Requires
            search_type=AGENTIC_COMPLETION; leave null otherwise.
          examples:
            - null
        tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tools
          description: >-
            Whitelist of tool names available to the agentic retriever. Requires
            search_type=AGENTIC_COMPLETION.
          examples:
            - null
        maxIter:
          anyOf:
            - type: integer
            - type: 'null'
          title: Maxiter
          description: >-
            Maximum agentic tool-call iterations before forcing a final answer
            (positive integer; AGENTIC_COMPLETION only).
          examples:
            - null
        includeReferences:
          type: boolean
          title: Includereferences
          description: Attach source references to completion-type results.
          default: false
        codeQuery:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Codequery
          description: >-
            Structured arguments for search_type=CODE. Set operation to
            query_facts, explore, traverse, find_path, or impact_analysis.
      type: object
      title: SearchPayloadDTO
    SearchResult:
      properties:
        search_result:
          title: Search Result
        dataset_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Dataset Id
        dataset_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Dataset Name
      type: object
      required:
        - search_result
        - dataset_id
        - dataset_name
      title: SearchResult
    cognee__api__DTO__ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      required:
        - error
      title: ErrorResponse
    SearchType:
      type: string
      enum:
        - SUMMARIES
        - CHUNKS
        - RAG_COMPLETION
        - HYBRID_COMPLETION
        - TRIPLET_COMPLETION
        - GRAPH_COMPLETION
        - GRAPH_COMPLETION_DECOMPOSITION
        - GRAPH_SUMMARY_COMPLETION
        - CYPHER
        - NATURAL_LANGUAGE
        - GRAPH_COMPLETION_COT
        - GRAPH_COMPLETION_CONTEXT_EXTENSION
        - FEELING_LUCKY
        - TEMPORAL
        - CODING_RULES
        - CHUNKS_LEXICAL
        - AGENTIC_COMPLETION
        - CODE
        - GRAPH_REPORT
      title: SearchType
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````