---
title: "Retrieve Memory"
method: POST
path: "/v1beta/memory/retrieve"
tags: ["Memory"]
---

# Retrieve Memory

`POST /v1beta/memory/retrieve`

Retrieves relevant or recent runs from the selected memory. Provide a query to rank results by relevance; leave it empty to return the most recent runs.

## Request body

- MemoryRetrieveRequest
  - `query` string, nullable — Concise query describing the memories to retrieve. Empty queries return the most recent memories.
  - `limit` integer — Maximum number of memories to return.
  - `kind` 'task' | 'monitor' | 'findall', nullable — Filter memories by kind: `task`, `monitor`, or `findall`.
  - `since` string, date-time, nullable — Only return memories sourced from task, monitor, or FindAll runs completed at or after this RFC 3339 timestamp.
  - `memory_scope_key` string, nullable — User-provided key identifying the memory scope to use. Omit to use personal memory, if available.

## Response `200`

Successful Response

- MemoryRetrieveResponse
  - `results` union[], required
    - union
      - TaskMemoryResult
        - `kind` 'task'
        - `id` string, required — ID of the task run.
        - `updated_at` string, date-time, required — When the run completed, as an RFC 3339 timestamp.
        - `input_excerpt` string, required — Preview of the run's input. May be truncated.
        - `output_excerpt` string, required — Preview of the run's output. May be truncated.
      - MonitorMemoryResult
        - `kind` 'monitor'
        - `id` string, required — ID of the monitor.
        - `updated_at` string, date-time, required — When the monitor last ran, as an RFC 3339 timestamp.
        - `input_excerpt` string, required — Preview of the monitor's query. May be truncated.
        - `status` 'active' | 'cancelled', required — Current status of the monitor.
        - `matched_events` MonitorMemoryEvent[] — Detected events matching the retrieval query, ordered by relevance with more recent events favored. For an empty query, events are ordered by recency.
          - `event_id` string, required — ID of the monitor event.
          - `event_group_id` string, required — ID of the execution that produced this event.
          - `detected_at` string, date-time, required — When the event was detected, as an RFC 3339 timestamp.
          - `excerpt` string, required — Excerpt of the monitor event. May be truncated.
      - FindAllMemoryResult
        - `kind` 'findall'
        - `id` string, required — ID of the FindAll run.
        - `updated_at` string, date-time, required — When the FindAll result was last updated, as an RFC 3339 timestamp.
        - `input_excerpt` string, required — Preview of the run's objective. May be truncated.
        - `matched_count` integer, required — Current number of matched entities.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) · [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/parallel-web/parallel-api/revisions/1595294c8795/schema)