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.
context_format str: Shape of an only_context result — “context” (default, the bare retrieval context) or “prompt” (the full envelope a completion would receive: session guidance, conversation history, and the rendered user and system prompts).
session_id (Optional[str]): Session whose history and guidance feed the completion or the prompt preview; 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

POST

api

curl --request POST \
  --url https://api.cognee.ai/api/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What is Cognee?"
}
'

import requests

url = "https://api.cognee.ai/api/v1/search"

payload = { "query": "What is Cognee?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

[
  {
    "search_result": "<unknown>",
    "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "dataset_name": "<string>"
  }
]

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query

string

required

The question to answer. Required; there is no default query.

Example:

"What is in the document?"

searchType

enum<string>

default:HYBRID_COMPLETION

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

Available options:

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

datasets

string[] | null

Dataset names to search. Names only resolve to datasets owned by the caller; use dataset_ids for datasets shared with you.

Example:

["default_dataset"]

datasetIds

string<uuid>[] | null

Dataset UUIDs to search (required for datasets shared with you). When provided, the datasets name list is ignored.

Example:

null

systemPrompt

string | null

default:Answer the question using the provided context. Be as brief as possible.

nodeName

string[] | null

Restrict results to nodes in these node_sets (the node_set values used during add/remember).

Example:

null

topK

integer | null

default:15

onlyContext

boolean

default:false

contextFormat

enum<string>

default:context

Shape of an only_context result. 'context' returns the bare retrieval context; 'prompt' returns the full envelope a completion would have received — session guidance, conversation history, and the rendered user and system prompts. The session layer comes from session_id (the default session when omitted). Ignored unless only_context is true.

Available options:

context,

prompt

Example:

"context"

sessionId

string | null

Session whose history and guidance feed the completion (or the only_context prompt preview). Omit to use the default session.

Example:

null

verbose

boolean

default:false

Return detailed result information including the graph representation when available.

skills

string[] | null

Skill names to load into the agentic retriever. Requires search_type=AGENTIC_COMPLETION; leave null otherwise.

Example:

null

tools

string[] | null

Whitelist of tool names available to the agentic retriever. Requires search_type=AGENTIC_COMPLETION.

Example:

null

maxIter

integer | null

Maximum agentic tool-call iterations before forcing a final answer (positive integer; AGENTIC_COMPLETION only).

Example:

null

includeReferences

boolean

default:false

Attach source references to completion-type results.

codeQuery

Codequery · object | null

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.

Response

Successful Response

search_result

any

required

dataset_id

string<uuid> | null

required

dataset_name

string | null

required

⌘I

curl --request POST \
  --url https://api.cognee.ai/api/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What is Cognee?"
}
'

import requests

url = "https://api.cognee.ai/api/v1/search"

payload = { "query": "What is Cognee?" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

[
  {
    "search_result": "<unknown>",
    "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "dataset_name": "<string>"
  }
]

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}

{
  "error": "<string>",
  "detail": "<string>"
}