> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Recall memory

> Search memory with a natural-language query and get ranked hits, confidence, and usage.

This is the REST version of **`tex.recall`**. Use it before generation to get the memory your model should read. For **`mode`**, **`top_k`**, and confidence, see [Recall and ranking](/concepts/retrieval).

## Headers

```http theme={null}
Authorization: Bearer <access_token>
Content-Type: application/json
```

## Body

```json theme={null}
{
  "scope": {
    "org_id": "org_...",
    "session_id": "chat-1"
  },
  "q": "what does the user prefer?",
  "mode": "active",
  "top_k": 5,
  "include_timeline": false
}
```

<ParamField body="scope.org_id" type="string" required>
  Your org id. Minimum length is 1 character. The server still uses the JWT's `org_id` claim for tenancy; this field is required for request validation.
</ParamField>

<ParamField body="scope.session_id" type="string">
  Session to search. Optional. Falls back to the JWT's `session_id`.
</ParamField>

<ParamField body="q" type="string" required>
  Natural-language query. `min_length=1`.
</ParamField>

<ParamField body="mode" type="&#x22;active&#x22; | &#x22;deep&#x22;" default="&#x22;active&#x22;">
  Retrieval depth. See [Recall and ranking](/concepts/retrieval).
</ParamField>

<ParamField body="top_k" type="integer">
  Hits to return across all kinds. **Defaults to 15 (active) / 25 (deep).** Request validation accepts `1 <= top_k <= 50`; runtime caps the final value at **30**.
</ParamField>

<ParamField body="include_timeline" type="boolean" default="false">
  Attach a chronological summary string to the response.
</ParamField>

## Response — `200`

<ResponseField name="hits.turns" type="array">
  Ranked raw turns.
</ResponseField>

<ResponseField name="hits.observations" type="array">
  Atomic facts.
</ResponseField>

<ResponseField name="hits.entities" type="array">
  Linked entities. Each entity has `{id?, label, score}`. This is different from turns and observations.
</ResponseField>

<ResponseField name="confidence" type="number">
  Calibrated \[0, 1].
</ResponseField>

<ResponseField name="timeline" type="string | null">
  Pre-rendered chronological summary, set only when `include_timeline=true`.
</ResponseField>

<ResponseField name="mode" type="string">
  Echoes request mode.
</ResponseField>

<ResponseField name="usage" type="object">
  `{tokens_in, tokens_out}` for this call.
</ResponseField>

### Hit fields

```json theme={null}
{
  "id": "c9fcfbf51b03bbc3...",
  "text": "[user] I'm allergic to shellfish.",
  "score": 0.42,
  "kind": "turn",
  "timestamp": "1778061473326"
}
```

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.getmetacognition.com/recall \
    -H "Authorization: Bearer $JWT" \
    -H 'content-type: application/json' \
    -d '{
      "scope": {"org_id":"org_…","session_id":"chat-1"},
      "q": "any food restrictions?",
      "top_k": 3
    }'
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.post(
      "https://api.getmetacognition.com/recall",
      headers={"Authorization": f"Bearer {jwt}"},
      json={
          "scope": {"org_id": "org_…", "session_id": "chat-1"},
          "q": "any food restrictions?",
          "top_k": 3,
      },
      timeout=10,
  )
  hits = resp.json()
  for t in hits["hits"]["turns"]:
      print(f"[{t['score']:.2f}] {t['text']}")
  ```
</CodeGroup>

```json Response theme={null}
{
  "hits": {
    "observations": [],
    "turns": [
      {
        "id": "c9fcfbf5...",
        "text": "[Date: 2026-05-08T14:00:00Z] [user] I'm allergic to shellfish",
        "score": 0.4268,
        "kind": "turn",
        "timestamp": "1778061473326"
      }
    ],
    "entities": []
  },
  "timeline": null,
  "confidence": 0.067,
  "mode": "active",
  "usage": { "tokens_in": 6, "tokens_out": 27 }
}
```