Skip to main content
POST
cURL
List memories scoped by filters with paginated results. Entity IDs (user_id, agent_id, app_id, run_id) must be passed inside the filters object: top-level entity IDs are rejected with 400. Expired memories are hidden by default. Pass show_expired: true to include memories whose expiration_date has passed. Python uses show_expired; TypeScript uses showExpired. The filters object supports complex logical operations (AND, OR, NOT) and comparison operators:
  • in: Matches any of the values specified
  • gte: Greater than or equal to
  • lte: Less than or equal to
  • gt: Greater than
  • lt: Less than
  • ne: Not equal to
  • icontains: Case-insensitive containment check
  • *: Wildcard character that matches everything
Pass page and page_size as query parameters to paginate through results.
The response is a paginated envelope with count, next, previous, and results. Use page and page_size query params to step through results.

Query Parameters

page
integer
default:1

1-indexed page number.

Required range: x >= 1
page_size
integer
default:100

Results per page.

Required range: 1 <= x <= 200

Body

application/json
filters
object
required

Entity and metadata filters. Must include at least one entity ID (user_id, agent_id, app_id, or run_id).

show_expired
boolean
default:false

When true, include memories whose expiration_date has passed. Expired memories are hidden by default.

Response

Paginated envelope of memories.

count
integer
required

Total number of memories matching the filters.

next
string<uri> | null
required

URL for the next page, or null if this is the last page.

previous
string<uri> | null
required

URL for the previous page, or null if this is the first page.

results
object[]
required