> ## 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 (low level): run one SearchType over the caller's datasets > 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: Return what the LLM would have received instead of its answer. For completion type searches the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is `system_prompt_result` with verbose=true. Retrieval-only types return their context. No LLM call is made. - **session_id** (Optional[str]): Session whose history and guidance feed the completion or the only_context prompt; the default session when omitted. - **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://{tenant}.aws.cognee.ai description: 'Cognee Cloud: your tenant pod, named in the platform.cognee.ai dashboard' variables: tenant: default: your-tenant description: Your tenant name, shown in the Cognee Cloud dashboard - url: http://localhost:8000 description: 'Self-hosted: a locally running cognee server' security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: activity description: >- Activity endpoints for inspecting pipeline runs, traced spans, tenant users, agents, and dataset exports. - name: add description: Data ingestion endpoints for adding text, files, and structured data. - name: agent connections description: >- Endpoints for registering, unregistering, and inspecting agent connections to the instance. - name: agent management description: Endpoints for creating, listing, retrieving, and deleting agents. - name: auth description: >- Authentication endpoints for user registration, login, and token management. - name: checks description: >- Diagnostic endpoint for validating a Cognee Cloud API key supplied in the X-Api-Key header. - name: cognify description: >- Knowledge processing endpoints to transform raw data into knowledge graphs. - name: configuration description: >- Endpoints for storing, retrieving, and listing a user's saved configurations. - 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: Endpoint for removing data from the knowledge graph. - name: health description: Liveness, readiness, and component health checks. - name: improve description: Endpoint for enriching and improving an existing knowledge graph. - name: integrations description: >- Endpoints for connecting, provisioning, and disconnecting OAuth providers and plugins. - name: llm description: >- LLM-backed endpoints for inferring graph schemas and generating custom extraction prompts. - name: memify description: >- Endpoint for running enrichment pipelines over existing graphs or supplied data. - name: ontologies description: >- Endpoints for uploading, listing, and deleting ontology files used during cognify. - name: permissions description: Permission management for multi-user access control. - name: recall description: >- Endpoints for querying the knowledge graph and reviewing past recall history. - name: remember description: >- Endpoints for ingesting data into the knowledge graph and storing session memory entries. - name: responses description: Response generation endpoints using the knowledge graph. - name: schema description: >- Schema inspection endpoints for a dataset's derived schema inventory and the caller-wide memory provenance graph. - name: search description: Search endpoints for querying the knowledge graph. - name: sessions description: >- Endpoints for listing sessions and reporting usage, cost, and token statistics. - name: settings description: Configuration endpoints for managing Cognee settings. - name: skills description: >- Skill management endpoints for ingesting, listing, retrieving, and deleting dataset skills, plus read-only retrieval of improvement proposals. - name: slack description: >- Endpoints for listing workspace channels, setting channel allowlists, and linking Slack accounts. - name: sync description: Endpoints for syncing local data to Cognee Cloud and checking sync status. - name: update description: Endpoint for updating existing data in a dataset. - name: users description: User management endpoints. - name: validate description: >- Diagnostic endpoint for checking consistency between a dataset's graph and vector stores. - name: visualize description: Graph visualization endpoints. paths: /api/v1/search: post: tags: - search summary: 'Search (low level): run one SearchType over the caller''s datasets' 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: Return what the LLM would have received instead of its answer. For completion type searches the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is `system_prompt_result` with verbose=true. Retrieval-only types return their context. No LLM call is made. - **session_id** (Optional[str]): Session whose history and guidance feed the completion or the only_context prompt; the default session when omitted. - **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': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/cognee__api__DTO__ErrorResponse' 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 description: The question to answer. Required; there is no default query. examples: - 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 description: >- Return what the LLM would have received instead of its answer. For completion search types the result is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block); the system prompt (the retriever's task template) is system_prompt_result with verbose=true. The session layer comes from session_id (the default session when omitted). Retrieval-only types return their context. No LLM call is made and nothing is written to the session. default: false sessionId: anyOf: - type: string - type: 'null' title: Sessionid description: >- Session whose history and guidance feed the completion (or the only_context prompt). Omit to use the default session. examples: - null 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, impact_analysis, insights, architecture, or delta. Add diagram='mermaid' (or 'dot', or true) to receive the result rendered as diagram source under search_result[0].diagram; architecture includes a Mermaid diagram unless diagram=false. type: object required: - query 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 description: >- Error body returned by routers that answer 4xx/5xx themselves. ``error`` is the human-readable message. Errors raised as ``CogneeApiError`` are rendered instead by the app-level handler in ``cognee/api/client.py`` as ``{"detail": " []"}`` plus ``"remediation"`` when a fix is known. 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 - SKILLS title: SearchType securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````