---
title: "Recall"
method: POST
path: "/v1/agents/{agent}/recall"
tags: ["agents"]
---

# Recall

`POST /v1/agents/{agent}/recall`

## Request

- Base URL: `https://innernet.live/api`
- URL: `https://innernet.live/api/v1/agents/{agent}/recall`
- Auth: HTTP bearer

Find the agent's memories for a question. Candidates are opened and ranked by the words of `query`, how recent and how important they are (`rerank` re-reads the best by meaning), anything under `threshold` goes, then `limit`. This is a search, so a key with only the `read` scope may use it (it is a POST because it carries a body). Without a `user_id` or a `subject` it reads what the agent knows and what it knows of its owner, and NOT its users: name a `user_id` to read one user's. `include_person` adds the person's own facts, only as deep as the agent's `person.read` allows (and each self or private fact that leaves is logged against the key for the person to see). A paused agent answers 423.

## Path parameters

- `agent` string, required

## Request body

- object
  - `query` string
  - `filters` object: The filter language: `and` / `or` / `not` over `kind`, `subject`, `user_id`, `run_id`, `tags`, `importance`, `confidence`, `immutable`, `source`, `created_at`, `updated_at`, `event_at`, `expires_at`, `about_you` and `metadata.<key>`, with `eq ne in nin gt gte lt lte contains exists`. A bare value means `eq`. Example: `{ "and": [ { "kind": { "in": ["fact", "preference"] } }, { "metadata.plan": "pro" } ] }`.
  - `user_id` string: One of the agent's users: reads that user's memories.
  - `run_id` string
  - `subject` 'agent' | 'owner' | 'user'
  - `kinds` string[]
  - `limit` integer: Default: the agent's `recall.limit`.
  - `threshold` number
  - `rerank` boolean
  - `include_person` boolean
  - `include_expired` boolean
  - `since` string, date-time: Kept at or after this.
  - `until` string, date-time: Kept before or at this.

## Response `200`

OK

- object
  - `memories` AgentMemory[]
    - `id` string, uuid
    - `agent` string: The agent's slug.
    - `content` string, nullable
    - `kind` 'fact' | 'preference' | 'episode' | 'procedure' | 'instruction' | 'note'
    - `subject` 'agent' | 'owner' | 'user': Who it is about: the agent's own knowledge, the person who owns the agent, or one of its users.
    - `user_id` string, nullable: Your end user, when `subject` is `user`.
    - `run_id` string, nullable
    - `tags` string[]
    - `metadata` object
    - `importance` integer
    - `confidence` number, nullable
    - `immutable` boolean
    - `source` 'api' | 'extract' | 'dashboard' | 'import'
    - `event_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `supersedes` string, uuid, nullable: The memory this one is the next version of.
    - `superseded_at` string, date-time, nullable: Set once a newer version has replaced this one.
    - `about_you` object, nullable: Set when the memory is about the person who owns the agent: where it stands with them.
      - `state` 'held' | 'kept' | 'declined' | 'auto'
      - `dimension` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `score` number: Only on recall and context results: 0 to 1.
  - `person` object[]: The person's own facts this agent may read, when `include_person`. `voice` says whose words: said, reported or inferred.
    - `statement` string
    - `dimension` string
    - `voice` string, nullable
    - `as_of` string, date-time, nullable
  - `meta` object
    - `considered` integer
    - `returned` integer
    - `latency_ms` integer
    - `reranked` boolean
    - `person_read` 'none' | 'standard' | 'personal' | 'private'

## Other responses

- `400`: Error: a field or a filter is wrong; `detail.field` names it (`invalid`)
- `401`: Error
- `403`: Error: this key cannot read (`forbidden`)
- `404`: Error: no such agent for this key (`not_found`)
- `423`: Error: the agent is paused (`paused`)
- `429`: Error: over the agent's reads a minute (`rate_limited`; `Retry-After: 60`)
- `503`: Error: agents are not switched on yet (`unavailable`)

---

[API](https://skmtc.dev/innernet/apis/innernet-api.md) · [All operations](https://skmtc.dev/innernet/apis/innernet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/innernet/apis/innernet-api/revisions/1ee09aec71a9?raw)