Guides

Filtering by time

How to scope search, retrieval, and list results to a time window with since, until, and last_n_days — and why combining a time window with an entity or tag filter is the highest-leverage query for longitudinal memory.

Most real-world questions are implicitly time-bound. "What did this customer report recently?" "Show me notes from this patient's sessions in the last three months." "What changed since the last release?" Aether lets you express that window directly on search, retrieve, and list, so you filter on the server instead of over-fetching and trimming results in your application.

The killer use case: a time window plus an entity filter

Time filters compose with the entity_id filter and with tag filters. That combination is the dominant query for therapy notes, customer-history timelines, and any longitudinal memory store:

"Show me notes from this patient's sessions in the last 3 months that mention anxiety."

The entity (or tag) filter narrows the store to one subject; the time window (last_n_days=90) narrows it to the relevant period; the semantic query ("anxiety") ranks what's left. Each filter is applied before vector search, so they make retrieval both faster and more precise. See combining filters below for the full example.

The three parameters

since, until, and last_n_days are accepted by search, retrieve, search_by_vector, and list. They filter on each document's created_at timestamp.

ParameterTypeSemantics
sinceRFC 3339 timestampOnly documents created on or after this instant (inclusive).
untilRFC 3339 timestampOnly documents created on or before this instant (inclusive).
last_n_dayspositive integerShorthand for since = now − N days (UTC).

A few notes on behavior:

  • Both bounds are inclusive. A document created at exactly since or exactly until is included.
  • since and until can be used together to express a closed interval, or independently for an open-ended window. since must not be after until (otherwise the request is rejected with 400).
  • last_n_days is mutually exclusive with since. Pass one or the other — sending both returns 400. You can combine last_n_days with until to cap a recent window.
  • Timestamps are RFC 3339 strings. Use a UTC instant such as 2026-04-01T00:00:00Z, or any offset form like 2026-04-01T00:00:00-07:00. The SDKs pass them through as-is; format the string yourself rather than passing a native date object.

Filters run before vector search

Time windows are applied as a pre-filter — before the vector search and reranking, not after. Narrowing the window shrinks the candidate pool the ranker has to consider, so a tight window is a performance win, not a cost. (max_distance, by contrast, prunes after reranking.)

last_n_days: the "recent" shorthand

When you just want the recent past, last_n_days is the shortest path — no timestamp arithmetic required. Here, retrieve the most relevant passages from the last 30 days:

curl "https://api.aetherdb.ai/search?q=deployment%20incidents&k=5&last_n_days=30" \
  -H "Authorization: Bearer $AETHER_API_KEY"

Explicit since / until

For a fixed reporting window — a quarter, a billing period, an incident timeline — pass since and until as RFC 3339 timestamps. Either bound is optional: omit until for "everything since X", omit since for "everything up to Y".

curl "https://api.aetherdb.ai/search?q=quarterly%20goals&k=10&since=2026-01-01T00:00:00Z&until=2026-03-31T23:59:59Z" \
  -H "Authorization: Bearer $AETHER_API_KEY"

Combining a time window with an entity or tag filter

This is the query that motivates the whole feature. Narrow to one subject with entity_id (or a tag), scope to a period with a time window, and rank the survivors by semantic relevance — all in a single call.

curl "https://api.aetherdb.ai/search?q=anxiety&k=5&last_n_days=90&entity_id=patient-1234" \
  -H "Authorization: Bearer $AETHER_API_KEY"

Prefer free-form tags? Swap entity_id for a tags filter (tags=["patient:1234", "session-note"]) — it composes with the time window the same way. Either way, both filters are applied before scoring, so this is dramatically faster, and more precise, than retrieving broadly and filtering by date in your application.

Listing within a time window

The same parameters work on list, which is the right tool when you want documents by recency rather than by semantic relevance — a "recent activity" feed, an audit view, or an export for a date range.

Time-filtered list results are returned newest-first (most recent created_at first, deterministic across pages), so the first page is the most recent activity. Without a time filter, list uses its default pagination order. Each document record carries its created_at timestamp.

curl "https://api.aetherdb.ai/documents?limit=50&last_n_days=7" \
  -H "Authorization: Bearer $AETHER_API_KEY"

For an explicit interval, swap last_n_days for since / until on list exactly as you would on search:

recent = client.list(
    limit=50,
    since="2026-04-01T00:00:00Z",
    until="2026-04-30T23:59:59Z",
)

Time windows apply to vector search too. On the HTTP API, search and documents take the time parameters as query-string params (shown above); search/embed takes them as JSON body fields alongside the embedding vector. In the SDKs, search_by_vector accepts the same since / until / last_n_days options as search.

curl -X POST "https://api.aetherdb.ai/search/embed" \
  -H "Authorization: Bearer $AETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding": [0.1, 0.2, 0.3],
    "k": 5,
    "last_n_days": 90
  }'

Next steps