---
title: "How requests behave"
description: "Acceptance, completion, replacement, recall and deletion, as your application observes them."
canonical: https://past.dev/docs/memory-api/how-it-works
last-updated: 2026-10-09
---
# How requests behave

> Acceptance, completion, replacement, recall and deletion, as your application observes them.

Product: past.dev Memory API. Source: https://past.dev/docs/memory-api/how-it-works

1. **Accept** A successful send returns an ingestion id after the request is durably accepted.
2. **Complete** Background processing continues after acceptance. Poll `GET /api/v1/ingest/{ingestionId}` until `status` is `completed`; the memory of that send is then readable.
3. **Recall** Recall returns up to the evidence budget `level` or `maxTokens` names: the memories that answer the query, each with artifact context and grouped source evidence.
4. **Forget** A deletion removes the data points and every memory that rests only on them, at once. A memory that also rests on other data points stays, readable by whoever can read those.

### Completion status

A send has two `status` vocabularies. The receipt of `POST /api/v1/ingest` says `queued`, or `completed` when nothing changed. `GET /api/v1/ingest/{ingestionId}` says `processing`, `completed` or `failed` for that send.

`settled`, `blocked` and `readiness` describe every send in the project. The four counters count sends: `raw` accepted and not started, `comprehension` in progress, `consolidation` reserved and always 0 today, `failed` stopped. `settled` is true when the first three are 0 and no send has failed. `blocked` is true when only failed sends remain.

A failed send stopped on an error. It does not clear on its own, and its data points are kept. Its status carries `failure` with a `code` and a `message`. Run it again with `POST /api/v1/ingest/{ingestionId}/retry`, free. If it stops again, write to support@past.dev with the `ingestionId` and the `X-Request-Id` of the send. A re-send with the same content changes nothing; a re-send with changed content is processed as a new version.

Before a send is `completed`, a recall can return its data points as `source` documents and none of the memory derived from them yet. Polls spend no credits and are outside the per-minute limit.

### Source replacement

A caller-supplied `id` is stable within the project. A send with the same id whose content, label, metadata and timestamp all match what is stored returns `200` with `unchanged: true`. A change to any of the four is a new revision, processed and charged: it replaces the data point and the memory that depended on the previous version. A send with the same content and another audience moves the data point to that audience and derives nothing new. On a re-send, every omitted field keeps its stored value except `audience`, which resets to project-visible; send `audience` on every re-send of a scoped data point. A deleted id is refused when sent again; use a new id.

### Idempotency keys

`idempotencyKey` makes a send replay-safe across processes. The same key with the same body returns the original receipt, also while the first request is in flight, starts nothing new and spends no credits. The same key with a different body returns `409 idempotency-conflict`. Send an explicit `timestamp` on every data point of a keyed request: an omitted timestamp takes the send time, which makes the retry a different body. Keys belong to the project and never expire.

### Retries

- `429` with no body: the per-minute limit. Wait one second, retry, and double the pause on each further `429`. There is no fixed limit on parallel sends beyond that rate.
- `429 project-cap-reached`: the project's monthly cap. Stop sends until the month resets; recall continues to serve.
- `429 spend-cap-reached`: the account's spend cap for the billing period. Priced calls resume when the period resets or the cap is raised.
- `402 out-of-credits`: the organization's credits are spent. Do not retry: waiting does not change the answer. `data.creditsLeft` and `data.creditsNeeded` say how far short the call fell, and `data.resetsOn` when the included credits come back, null on Pay as you go. Buy credits to continue.
- `5xx`, a timeout or a dropped connection: retry the same request with the same `idempotencyKey`. `503 organization-not-ready` clears within minutes. `503 pipeline-disabled` is a deployment setting.
- Any other `4xx`: fix the request. The same request again gives the same answer.

### Point in time

`queryTimestamp` sets the perspective of a recall. Evidence that occurred at or before that instant is eligible, and later evidence is out of scope. It defaults to the time of the call. `occurredFrom` and `occurredTo` narrow the read to a window of occurrence time, both bounds inclusive. The window intersects with the perspective, so a window that lies after `queryTimestamp` matches nothing. A window whose start is after its end returns `400 recall-range-invalid`.

```curl
curl -X POST https://api.past.dev/api/v1/recall \
  -H "Authorization: Bearer $PAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is the Acme pilot budget?", "identity": "demo-user", "queryTimestamp": "2026-03-01T00:00:00Z" }'
```

This read sees the February value of the Quickstart as the current one. The July data point occurred after the perspective and is out of scope.

### Identity and audience

A data point names the audience that can read it. A recall names the identity it answers as, and reaches that identity's audiences. [Concepts](/docs/memory-api/concepts) defines both, and [Access control](/docs/memory-api/access-control) shows how to place customers, companies and deals.

### Request ids

Every `/api/v1` response, success or refusal, carries an `X-Request-Id` header that begins with `req_`. The console's Requests screen lists each call under that id. A client-supplied `X-Request-Id` is not echoed.

### Health

`GET /health` is public on every deployment, cloud included, and returns `status`, `name` and `version`. A release image reports its release version; a build from source reports `dev`.

### Credits and limits

On the cloud service, sends are metered in credits: one credit per 350 bytes of UTF-8 content, rounded up per data point, with at least one credit per data point, summed over a batch. Only the data points that start ingestion are charged: a new data point, or a new revision of one. An unchanged re-send, a re-send that only changes the `audience`, and a replay of an `idempotencyKey` cost nothing, and they are not refused at zero credits. Polls and deletion spend no credits, and a refused call costs nothing. A recall costs a tenth of a credit on Pay as you go, the one plan where reading is metered, and nothing on Flex and Enterprise. When the organization's credits are spent, a send returns `402 out-of-credits`. On Flex and Enterprise recall continues to serve. On Pay as you go a recall returns `402 out-of-credits` too, because that plan charges for it.

A project can carry its own monthly caps on data points and credits, set under Settings, Projects in the console. A reached cap returns `429 project-cap-reached` until the month resets. No plan caps the number of recall calls: a recall is never refused for an allowance.

Requests per minute follow the plan of the key's organization: 500 on Pay as you go, 750 on Flex and 1,000 on Enterprise, counted for each key over a fixed one-minute window on sends, recalls and answers. A request over the limit returns `429` with no body.

The plan also caps the evidence one recall returns and the number of projects. A recall returns up to 8,000 tokens of evidence on Pay as you go and Flex and up to 32,000 on Enterprise: a larger `maxTokens` is lowered to that ceiling before the read, and `usedEvidenceTokens` reports what the page carried. An organization holds 1 project on Pay as you go, 5 on Flex and any number on Enterprise, archived projects included, and a project past that count returns `402 project-limit-reached`.