---
title: "Verb-shaped agent retrieval — active or deep mode"
method: POST
path: "/recall"
tags: ["recall"]
---

# Verb-shaped agent retrieval — active or deep mode

`POST /recall`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/recall`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/recall/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- RecallRequest
  - `scope` union, required: Tenant scope dict (legacy) OR a hierarchical scope string "<kind>:<value>" narrowing the read to that visible scope
    - string
    - Scope: Multi-tenant scope.
      - `org_id` string, required: Organization ID
      - `user_id` string, nullable: User ID
      - `session_id` string, nullable: Session ID
  - `session_id` string, nullable: Explicit session id, honored on the string-scope path
  - `q` string, required: Query text (at most 4096 characters)
  - `mode` 'active' | 'deep': Retrieval mode
  - `top_k` integer, nullable: Override default top_k
  - `min_score` number, nullable: Drop hits scoring below this. Without it, recall returns its full top_k nearest neighbours whatever their relevance — so escalating to the deep tier 'when active recall comes back empty' never fires against a non-empty store. Escalate on this threshold, not on an empty result.
  - `include_timeline` boolean: Attach a chronological timeline string to the response
  - `agent_id` string, nullable: Agent identifier for retrieval scoping; falls back to default-agent if unset
  - `probable_answer` boolean: Ask for `probable_answer` in the response (default true). False skips it; the list is the same either way.

## Response `200`

Successful Response

- RecallResponse
  - `hits` RecallHits, required
    - `observations` RecallHit[]
      - `id` string, nullable
      - `text` string, required
      - `score` number, required
      - `kind` 'turn' | 'observation' | 'entity'
      - `timestamp` string, nullable: Capture time, ISO 8601 UTC
      - `timestamp_ms` integer, nullable: Capture time, epoch milliseconds
      - `time_uncertain` boolean: True when the turn's timestamp was not understood and the capture time is the arrival time
    - `turns` RecallHit[]
      - `id` string, nullable
      - `text` string, required
      - `score` number, required
      - `kind` 'turn' | 'observation' | 'entity'
      - `timestamp` string, nullable: Capture time, ISO 8601 UTC
      - `timestamp_ms` integer, nullable: Capture time, epoch milliseconds
      - `time_uncertain` boolean: True when the turn's timestamp was not understood and the capture time is the arrival time
    - `entities` RecallEntity[]
      - `id` string, nullable
      - `label` string, required
      - `score` number, required
  - `timeline` string, nullable
  - `confidence` number, required: Relative confidence, NOT a calibrated probability. It is a sigmoid over the reranker's top-1 logit whose constants were never fitted (see services/retrieval_pipeline.py). It orders results correctly; its absolute value means nothing, so do not threshold on it — use min_score.
  - `mode` 'active' | 'deep', required
  - `usage` Usage: Token usage for a metered API call. Surfaced on every metered response so developers can see the cost of each call inline — mirrors OpenAI / Anthropic ``usage`` objects so the Tex bill is denominated in the same unit they already track for their LLM provider. Tokens are counted server-side with the ``cl100k_base`` encoding (matches ``text-embedding-3-large``).
    - `tokens_in` integer: Tokens in the request payload
    - `tokens_out` integer: Tokens in the response payload
  - `active_tier_error` string, nullable: Set when the active-memory tier failed during this call; hits then come only from the remaining tier(s) (degraded, not empty-by-design).
  - `deep_tier_error` string, nullable: Set when the deep (graph) tier failed during this call; hits then come only from the active tier (degraded, not empty-by-design).
  - `probable_answer` ProbableAnswer: The memory that most probably answers the question, by sense.
    - `id` string, required: Id of the chosen hit; always one of the hits in this response
    - `text` string, required: The chosen hit's text, as in the list
    - `timestamp` string, nullable: The chosen hit's capture time, as in the list
    - `probability` number, required: Probability that this memory is the answer (0..1)
    - `question_time` 'current' | 'past' | 'date' | 'ever' | 'future' | 'timeless', required: What time the question was read as being about
    - `alternatives` ProbableAnswerAlternative[]: Up to two other hits that might be the answer, with their probabilities
      - `id` string, required: Id of another hit in the list
      - `probability` number, required
  - `probable_answer_reason` 'no_memory_answers' | 'unavailable' | 'not_enabled', nullable: Why probable_answer is null (null when it is set): no_memory_answers = no memory in the list answers the question; unavailable = it could not be worked out this time; not_enabled = not requested or not enabled for this deployment.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)