---
title: "Retrieve ranked memory documents"
method: POST
path: "/api/v1/recall"
tags: ["recall"]
---

# Retrieve ranked memory documents

`POST /api/v1/recall`

## Request

- Base URL: `https://api.past.dev`
- URL: `https://api.past.dev/api/v1/recall`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Return one authoritative JSON result per selected document, with artifact context and document-local source evidence. Consumers own prompt, model, and display rendering.

## Request body

- RecallRequest
  - `query` string, required: Natural-language query.
  - `limit` integer: Maximum number of documents in the page.
  - `level` 'low' | 'medium' | 'high' | 'extra-high': The evidence budget in words: low 8,000 tokens, medium 16,000, high 24,000, extra-high 32,000. A level above the plan's ceiling is lowered to it: 8,000 on Pay as you go and Flex, 32,000 on Enterprise. Send level or maxTokens, never both.
  - `maxTokens` integer: An explicit evidence budget in tokens, for a caller who needs a figure the levels do not offer. Estimated from document content and excerpt text only, excluding JSON structure and metadata; lowered to the plan's ceiling in the same way; whole documents are kept or omitted.
  - `queryTimestamp` string, date-time: The perspective of the read. Evidence at or before this instant is eligible. Defaults to now.
  - `occurredFrom` string, date-time: Inclusive start of the occurrence window.
  - `occurredTo` string, date-time: Inclusive end of the occurrence window. A start after the end returns 400 recall-range-invalid.
  - `sort` 'relevance' | 'chronological': chronological orders the selected documents oldest first and keeps each relevance rank.
  - `identity` string, required

## Response `200`

Ranked document results with source excerpts and the UTC recall perspective.

- RecallResponse
  - `asOf` string, date-time, required
  - `usedEvidenceTokens` integer, required: Sum of per-document character-based estimates for content and excerpt text only; excludes JSON structure, IDs, dates and metadata. Not model-provider usage.
  - `results` RecallResult[], required
    - `id` string, uuid, required
    - `rank` integer, required
    - `occurredAt` string, date-time, required
    - `content` string, required
    - `artifact` RecallArtifact, required
      - `id` string, uuid, required
      - `kind` string, required: source is an original data point. Any other value is the kind of a derived memory: observation, claim, rule, membership, identity, mention or temporal-anchor. The list can grow; treat an unknown value as a memory. The Concepts page of the docs defines each kind.
      - `occurredAt` string, date-time, required
      - `supersededAt` string, date-time: Present when a later statement readable by this viewer superseded the artifact.
    - `sources` RecallSource[], required
      - `sourceId` string, required
      - `occurredAt` string, date-time, required
      - `metadata` unknown
      - `label` string: The caller's label for the source, as sent at ingest; omitted when none was sent.
      - `excerpts` string[], required: Verbatim supporting quotations. Repeated quotations are preserved.

## Other responses

- `400`: The request is malformed or violates a field constraint. Match behavior on the response code field.
- `401`: missing-api-key: no bearer. malformed-api-key: the header or the key has the wrong shape, or an agent token was sent to a route that accepts keys only. unauthorized: the key is unknown, expired, revoked, or of the kind this route refuses, or the agent token is invalid or expired.
- `402`: out-of-credits, on Pay as you go only: a recall costs a tenth of a credit there, and the balance cannot pay for it. `data` carries `creditsLeft` and `creditsNeeded`. Flex and Enterprise never refuse a recall for credits.
- `403`: project-archived: the project of the key, or the project an agent token names, is archived. Unarchive it in the console to resume. insufficient-scope: the agent token does not carry the scope of the route.
- `429`: The plan's requests per minute are exceeded, which carries no body, or `spend-cap-reached` on Pay as you go. No plan caps the number of recall calls.
- `default`: Any other failure uses the same JSON error envelope.

---

[API](https://skmtc.dev/past/apis/past-dev-memory-api.md) · [All operations](https://skmtc.dev/past/apis/past-dev-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/past/apis/past-dev-memory-api/revisions/3ddccc19f0eb?raw)