> ## 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 & Recall

> Endpoints for querying knowledge graphs and retrieving data

These endpoints query your knowledge graphs. For the full parameter reference, see [Search Basics](/guides/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.

```bash theme={null}
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.

```bash theme={null}
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:

1. [`POST /api/v1/remember`](/cognee-cloud/functionality/data-ingestion#remember), **or**
2. [`POST /api/v1/add`](/cognee-cloud/functionality/data-ingestion#add) followed by [`POST /api/v1/cognify`](/cognee-cloud/functionality/knowledge-processing#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.                                               |

<Note>
  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.
</Note>

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

```bash theme={null}
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](/core-concepts/main-operations/legacy-operations/search).

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.

```bash theme={null}
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](/cognee-cloud/ui/knowledge-graph) for the built-in visualization.

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

<Info>
  `recall` is recommended for most use cases. Use `search` when you need to specify a particular retrieval strategy.
</Info>