recall

Recall: query memory with auto-routed search type and session-first lookup

Recall information from the knowledge graph.

This is a memory-oriented alias for the search endpoint. All search types and options from v1 are supported.

Request Parameters

Field names are shown camelCased in the schema (e.g. searchType, datasetIds, topK); both camelCase and snake_case are accepted.

search_type (Optional[SearchType]): Type of search to perform. Omit (default: null) to auto-route the query with the rule-based router (HYBRID_COMPLETION fallback); pass a value to pin one.
datasets (Optional[List[str]]): Dataset names to search within
dataset_ids (Optional[List[UUID]]): Dataset UUIDs to search within; take precedence over dataset names when both are provided
query (str): The search query string
system_prompt (Optional[str]): System prompt for completion searches
node_name (Optional[List[str]]): Filter to specific node sets
top_k (Optional[int]): Maximum results (default: 15)
only_context (bool): Return what the LLM would have received instead of its answer — for completion types each item’s text is the user prompt (conversation history, question plus retrieval context, session guidance) and its system_prompt field the retriever’s task template; retrieval-only types return their context
verbose (bool): Verbose output
include_references (bool): Include source/provenance references in completion results (default: true)
stream (Optional[bool]): Stream the answer as server-sent events (text/event-stream). Defaults to content negotiation on Accept.
session_id (Optional[str]): Session whose cached QA and trace entries should be searched
scope (Optional[str | List[str]]): Memory sources to include: “graph”, “session”, “session_first”, “trace”, “session_context”, “tools”, “code”, “all”, “auto”, or a list of these (default: “auto” — session first when session_id is set, else graph). “session_first” requests that short-circuit explicitly rather than by omitting searchType. “code” is explicit opt-in only and returns deterministic code-graph facts tagged source=“code” (e.g. scope=[“graph”, “code”])
code_query (Optional[dict]): “code” scope only — operation and arguments for the code-graph query (same format as /v1/search code_query); omit for the default “explore” with the query text as seed
response_schema (Optional[dict]): JSON Schema for structured completion output; validated results land in each result’s structured field. 422 on schemas outside the supported subset.
contextProfile (str): Profile to render for the ‘session_context’ scope: ‘qa’ (conversational) or ‘agent’ (tool/workflow). Ignored by other scopes. Defaults to ‘qa’.
toolConnections (Optional[List[str]]): Names of authorized external database connections for the ‘tools’ scope. Omit to use every connection visible to the caller.
toolsTrigger (str): When the ‘tools’ scope runs: ‘always’, or ‘on_empty’ to query the external database only when every other requested source returned nothing. Defaults to ‘always’.

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
409 Conflict: Unexpected non-Cognee error during recall

POST

api

recall

Recall: query memory with auto-routed search type and session-first lookup

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

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/recall"

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

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

print(response.text)

[
  {
    "time": "<string>",
    "question": "<string>",
    "context": "<string>",
    "answer": "<string>",
    "source": "session",
    "qa_id": "<string>",
    "feedback_text": "<string>",
    "feedback_score": 123,
    "used_graph_element_ids": {},
    "memify_metadata": {},
    "used_session_context_ids": [
      "<string>"
    ]
  }
]

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

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

Search strategy, e.g. HYBRID_COMPLETION, GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS. Omit (or pass null) to let cognee auto-route the query (rule-based, no LLM call, HYBRID_COMPLETION fallback; see docs/recall-vs-search.md for the rule table). Pass a value to pin one.

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 within. Omit (null) to search all datasets you have read access to.

Example:

["default_dataset"]

datasetIds

string<uuid>[] | null

Dataset UUIDs to search within; takes precedence over 'datasets' names when both are provided. Leave empty to resolve by name.

Example:

null

systemPrompt

string | null

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

nodeName

string[] | null

Restrict results to these node sets (the node_set values passed to /v1/add or /v1/remember). Omit to search all nodes.

Example:

null

topK

integer | null

default:15

onlyContext

boolean

default:false

Return what the LLM would have received instead of its answer. For completion search types each item's text is the user prompt (conversation history, then question plus retrieval context through the retriever's template, then the session guidance block) and its system_prompt field carries the retriever's task template. Retrieval-only types return their context. No LLM call is made and nothing is written to the session.

verbose

boolean

default:false

includeReferences

boolean

default:false

Include source/provenance references in completion results.

sessionId

string | null

Session whose cached QA and trace entries should be searched. With search_type omitted the session becomes a search source: alone it short-circuits the graph on a hit, alongside datasets both contribute. Pinning search_type leaves the graph as the only source.

Example:

null

scope

Which memory sources to include: 'graph', 'session', 'session_first', 'trace', 'session_context', 'tools', 'code', 'all', 'auto', or a list of these. Defaults to 'auto' (session first when session_id is set, else graph). 'session_first' asks for that short-circuit explicitly — a session hit answers alone — instead of getting it by omitting search_type. 'tools' and 'code' are explicit opt-in only — never implied by 'auto' or 'all'. 'tools' requires TOOL_CALLS_ENABLED on the server; 'code' runs a deterministic code-graph query (see code_query) and tags results source='code'.

Example:

null

toolConnections

string[] | null

Names of authorized external database connections for the 'tools' scope. Omit to use every connection visible to the caller.

Example:

null

stream

boolean | null

Stream the answer as server-sent events. When omitted, the Accept header decides: streaming happens only for a client that ranks text/event-stream above application/json, so */* and the two listed together both stay on the JSON response.

toolsTrigger

string

default:always

When the 'tools' scope runs: 'always', or 'on_empty' to query the external database only when every other requested source returned nothing.

codeQuery

Codequery · object | null

'code' scope only: structured operation and arguments for the deterministic code-graph query (same format as /v1/search code_query, e.g. {"operation": "impact_analysis", "seeds": ["UserService"]}). Omit to run the default 'explore' operation with the query text as seed. A seed the code graph cannot resolve contributes no results rather than failing the recall.

Example:

null

contextProfile

string

default:qa

Profile to render for the 'session_context' scope: 'qa' (conversational) or 'agent' (tool/workflow). Ignored by other scopes.

responseSchema

Responseschema · object | null

JSON Schema for structured completion output (typically MyModel.model_json_schema()). The completion is validated against it and each result carries the validated payload in its 'structured' field. Supported by completion-style search types only. Structural subset: objects, primitives, arrays, enums, optionals, $defs references; value constraints (minLength, ...) are not enforced server-side.

Example:

null

Response

Successful Response

time

string

required

question

string

required

context

string

required

answer

string

required

source

string

required

Allowed value: "session"

qa_id

string | null

feedback_text

string | null

feedback_score

integer | null

used_graph_element_ids

Used Graph Element Ids · object | null

Show child attributes

memify_metadata

Memify Metadata · object | null

used_session_context_ids

string[] | null

⌘I

Recall: query memory with auto-routed search type and session-first lookup

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

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/recall"

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

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

print(response.text)

[
  {
    "time": "<string>",
    "question": "<string>",
    "context": "<string>",
    "answer": "<string>",
    "source": "session",
    "qa_id": "<string>",
    "feedback_text": "<string>",
    "feedback_score": 123,
    "used_graph_element_ids": {},
    "memify_metadata": {},
    "used_session_context_ids": [
      "<string>"
    ]
  }
]

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Getting Started

auth

add

cognify

memify

search

permissions

datasets

ontologies

settings

visualize

schema

skills

configuration

delete

validate

update

responses

llm

sync

users

checks

health

agent management

agent connections

activity

sessions

remember

recall

improve

forget

slack

integrations

Recall: query memory with auto-routed search type and session-first lookup

Request Parameters

Error Codes

Authorizations

Body

Response