Search & Recall

Endpoints for querying knowledge graphs and retrieving data

These endpoints query your knowledge graphs. For the full parameter reference, see Search Basics.

Recall

POST /api/v1/recall — Retrieve information from the knowledge graph.

Auto-routes the query to the best retrieval strategy. This is the primary search endpoint.

Results are ranked for the calling user: a completion-based search over a single dataset nudges ranking toward what that user has rated well, away from what they rated poorly, and carries their stated preferences as guidance. See Personalized ranking.

curl -X POST https://your-tenant.aws.cognee.ai/api/v1/recall \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What entities are in my data?"}'

query is a required body field: a request that omits it is rejected with 400 and a detail array naming the missing field, rather than being answered — see Requests without a query for the error shape and the history of the removed default.

The request body accepts an include_references boolean (default true). When enabled, completion-style answers get a deterministic Evidence: block appended to the answer text, citing the source chunks or graph context. The response schema is unchanged. Set include_references to false to restore the exact prior answer text.

curl -X POST https://your-tenant.aws.cognee.ai/api/v1/recall \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What entities are in my data?", "include_references": false}'

Streaming

A recall can stream its answer as server-sent events instead of waiting for the full JSON payload. Opt in with stream: true in the body, or an Accept header that ranks text/event-stream above application/json:

curl -N -X POST https://your-tenant.aws.cognee.ai/api/v1/recall \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query": "What entities are in my data?", "stream": true}'

The response is text/event-stream: stage frames name the phase (retrieving, generating), delta frames carry answer tokens, a reset frame tells the client to discard the partial text (the model call was retried), and the stream ends with a final frame carrying the same payload the JSON path returns — the streamed tokens are a preview, the final payload is authoritative. Keepalive comments pad quiet stretches.

Two boundaries to know:

• Token deltas need a streamable answer call. They flow for a session-backed completion — the path the Search UI uses. A sessionless recall, an only_context one, and a recall constrained by a response_schema all still return an event stream, but one carrying stage and final and no delta frames at all. Zero deltas is a supported outcome, not a failure. Callers that don’t opt in get the unchanged JSON response.
• The pre-flight credit guard still runs first: an exhausted balance is a real HTTP 402 before any stream starts, not an error frame inside a 200.

Session retention

Session-cache rows — Search-page conversations plus agent Q&A and trace entries — are kept for one year of inactivity. The TTL is re-stamped on every write, so only a conversation untouched for a full year expires. Before mid-September 2026 the window was cognee’s seven-day default.

Recall and search history

GET /api/v1/recall — Retrieve recall history for the authenticated user.

Recall records the questions it answers. A POST /api/v1/recall that runs graph retrieval writes its question and answer into the same history that POST /api/v1/search uses, so recall traffic — including questions from agents and the Search UI, which both call recall — appears in both GET /api/v1/recall and GET /api/v1/search.

What a recall records:

• The search type that ran. If you omit search_type, recall auto-routes the question, and the history row stores the type the router chose — HYBRID_COMPLETION for an ordinary question, or CHUNKS_LEXICAL / CODING_RULES when a routing rule matched.
• One question-and-answer entry per dataset that answered. A recall spanning several datasets records a separate pair for each, attributed to that dataset, rather than one combined entry. Recalls whose results carry no dataset — which is what happens when access control is disabled — are recorded without dataset attribution.
• Unanswered questions too. A recall that matched nothing still records one entry, unattributed, with empty answer text.

History is written after retrieval finishes, so the recorded search type and dataset reflect what actually ran. The write is not best-effort: if it fails, the request fails rather than returning an answer that was never recorded. Set COGNEE_LOG_SEARCH_HISTORY to false to stop recording history altogether.

Recall prerequisites

Recall reads from an existing knowledge graph — it does not create one. Before recall (or search) returns anything, the dataset must already be ingested and processed:

1. POST /api/v1/remember, or
2. POST /api/v1/add followed by POST /api/v1/cognify.

If you recall before the graph exists, the endpoint returns:

Status	Body	Meaning
422	{"detail": "Recall prerequisites not met: no database/default user found. Initialize Cognee before recalling by: ... [RecallPreconditionError]"}	No graph has been built yet for this user/dataset — ingest and cognify first. The detail string carries the full remediation steps.
402	{"detail": "LLM provider requires payment or token budget is exhausted. [LLMPaymentRequiredError]"}	The configured LLM provider (or LiteLLM proxy) reported that its token budget is exhausted. When the provider’s own budget sentence can be identified it replaces the generic wording, giving {"detail": "LLM budget exhausted: <provider sentence> [LLMPaymentRequiredError]"} — see 402 Payment Required. Handle 402 by surfacing a top-up / billing flow rather than retrying.
403	{"detail": "Request owner does not have necessary permission: [read] for all datasets requested. [PermissionDeniedError]"}	At least one dataset you named is not readable by you. When no dataset is named and you can read none at all, the message reads Request owner does not have permission: [read] for any dataset. instead.
404	{"detail": "Dataset(s) not found: 'typo'. Dataset names resolve only among the datasets you own in the current tenant; pass dataset_ids for datasets shared with you. [DatasetNotFoundError]"}	At least one name in datasets matches no dataset you own in this tenant. The whole request fails before any retrieval runs — the other named datasets are not searched — and every unresolved name is listed (duplicates once). Fix the name, or send dataset_ids with the dataset’s UUID, which is resolved as before. Recalls scoped only to session, trace, or session_context never resolve names and cannot return this.
409	{"error": "An error occurred during recall."}	An unexpected, non-Cognee error interrupted the request server-side.
409	{"detail": "Dataset ... was embedded with ... [EmbeddingDimensionMismatchError]", "remediation": "..."}	EMBEDDING_MODEL now produces a different vector width than the model that built this dataset. Terminal — see embedding dimension mismatch.
422	{"detail": "response_schema: unsupported JSON Schema keyword: allOf [CogneeValidationError]"}	The supplied response_schema falls outside the supported subset, or exceeds the depth/property budgets. Every message from this path is prefixed with response_schema: — for example recursive reference '#/$defs/Node', nesting deeper than 10 levels, or more than 200 properties in total. The schema is rebuilt before retrieval starts, so a rejected schema costs no retrieval or LLM work.

Errors raised inside Cognee reach the caller with their own status code and a single detail field of the form "<message> [<ErrorName>]" — see Error Handling.

Structured output with response_schema

The request body accepts an optional response_schema object: a JSON Schema describing the shape you want the completion to conform to, typically produced client-side with MyModel.model_json_schema(). The server rebuilds a Pydantic model from it and validates the completion against that model, so each result carries the validated payload in its structured field. Only completion-style search types support it.

from pydantic import BaseModel

class NLPFacts(BaseModel):
    field_name: str
    parent_disciplines: list[str]

NLPFacts.model_json_schema()
# {'properties': {'field_name': {'title': 'Field Name', 'type': 'string'},
#                 'parent_disciplines': {'items': {'type': 'string'}, ...}},
#  'required': ['field_name', 'parent_disciplines'],
#  'title': 'NLPFacts', 'type': 'object'}

curl -X POST https://your-tenant.aws.cognee.ai/api/v1/recall \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "What is NLP and which disciplines does it belong to?",
        "response_schema": {
          "type": "object",
          "title": "NLPFacts",
          "properties": {
            "field_name": {"type": "string"},
            "parent_disciplines": {"type": "array", "items": {"type": "string"}}
          },
          "required": ["field_name", "parent_disciplines"]
        }
      }'

The Python SDK sends this field for you: when recall(response_model=...) runs against a remote server, the client forwards response_model.model_json_schema() as response_schema.

Supported schema subset

The server accepts only the structural subset that Pydantic itself emits:

Supported	Rejected with 422
Root "type": "object" with non-empty properties	Any other root type, or an object with no declared properties
Primitives: string, integer, number, boolean, null	Missing or unrecognized type on a node
array with an items schema	array without items
enum of non-empty strings, integers, or booleans	Empty enums or enums of other value types
anyOf unions and optionals, and list-valued type	allOf, oneOf, not, patternProperties
Nested objects via #/$defs/... or #/definitions/... references	Recursive, unresolvable, or otherwise-prefixed $ref values

Two budgets guard the service against abusive schemas: nesting may not exceed 10 levels, and the schema may not declare more than 200 properties in total.

Value constraints such as minLength, minimum, or pattern are not enforced server-side, and Python-side custom validators do not travel with the schema — only the structure is reconstructed. To run your full validation logic, rehydrate the result against your own class on the client: NLPFacts.model_validate(result["structured"]).

Search

POST /api/v1/search — Search for nodes in the graph database.

Provides direct control over the retrieval strategy. Accepts a search_type parameter to select a specific search mode.

curl -X POST https://your-tenant.aws.cognee.ai/api/v1/search \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did Einstein develop?",
    "search_type": "GRAPH_COMPLETION",
    "datasets": ["physics_data"]
  }'

Available search types are documented in Search Types.

The request body also accepts an include_references boolean (default true), which behaves the same as on POST /api/v1/recall: it appends an Evidence: block to completion-style answer text. Set it to false to disable.

query is required here as well, on the same terms as on POST /api/v1/recall — see Requests without a query.

GET /api/v1/search — Retrieve search history for the authenticated user.

Searches are recorded per dataset. A POST /api/v1/search spanning several datasets records one question-and-answer entry for each dataset that answered, rather than a single combined entry, so history grows in proportion to the datasets a search touches. See Recall and search history for the full recording rules, which are shared by both endpoints.

Requests without a query

query is a required body field on both POST /api/v1/recall and POST /api/v1/search. A body that omits it fails request validation before any retrieval runs, and Cognee returns 400 — not the 422 that FastAPI emits by default — with the validation errors in detail:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "query"],
      "msg": "Field required",
      "input": {}
    }
  ],
  "body": {}
}

The fix is to send an explicit query string. This matters most for integrations written against earlier releases, where both endpoints declared query with a default of "What is in the document?": a {} body returned 200 with an answer to that placeholder question, searched across every dataset the caller could read. Those calls now fail loudly instead of returning an answer to a question nobody asked. Requests that already pass a real query — including every example on this page — are unaffected.

The placeholder string is still the schema example for the field, so the interactive reference and Swagger “Try it out” keep prefilling it in the request body. It is an example you can edit or replace, not a value the server substitutes when you leave query out.

The Python SDK is unaffected: recall() and search() already take the query as a required positional argument.

Visualize

GET /api/v1/visualize — Generate an HTML visualization of a dataset’s knowledge graph.

Requires a dataset_id query parameter (UUID). Returns a self-contained HTML page with an interactive graph.

curl "https://your-tenant.aws.cognee.ai/api/v1/visualize?dataset_id=<uuid>" \
  -H "X-Api-Key: your-key"

See also the Knowledge Graph UI for the built-in visualization.

POST /api/v1/visualize/multi — Generate a combined visualization from multiple users’ datasets.

recall is recommended for most use cases. Use search when you need to specify a particular retrieval strategy.