Search & Recall

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.

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?"}'

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}'

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

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:

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

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

Status	Body	Meaning
`422`	`{"error": "Recall prerequisites not met", "hint": "..."}`	No graph has been built yet for this user/dataset — ingest and cognify first.
`402`	`{"error": "Token budget exhausted", "detail": "..."}`	The configured LLM provider (or LiteLLM proxy) reported that its token budget is exhausted. Handle 402 by surfacing a top-up / billing flow rather than retrying.
`409`	`{"error": "An error occurred during recall."}`	The query ran but failed server-side (e.g. a transient processing error).
`200`	`[]`	Permission denied — returned as an empty successful result rather than an error to avoid leaking dataset existence.

A 200 response with an empty list can mean you lack read access to the dataset, not only that the dataset is empty. Confirm the dataset name and your permissions if recall returns [] unexpectedly.

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. GET /api/v1/search — Retrieve search history for the authenticated user.

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.

Getting Started

Local UI

Navigating the UI

Cloud Functionality

Connections

Reference

Recall

Recall prerequisites

Search

Visualize

​Recall

​Recall prerequisites

​Search

​Visualize

Recall

Recall prerequisites

Search

Visualize