---
title: "Accept an ordered batch"
method: POST
path: "/api/v1/ingest/batch"
tags: ["ingestion"]
---

# Accept an ordered batch

`POST /api/v1/ingest/batch`

## Request

- Base URL: `https://api.past.dev`
- URL: `https://api.past.dev/api/v1/ingest/batch`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Accept one atomic ordered batch containing 1 to 1,000 data points and at most 16 MiB of UTF-8 content.

## Request body

- IngestBatchRequest
  - `items` IngestItem[], required
    - `content` string, required: Raw text. Empty or whitespace-only content is refused.
    - `label` string: Optional short title for the data point, stored as its own field and returned as label on recall sources. Omitted on a re-send, the stored label stays.
    - `id` string: Stable source id. When omitted, the lowercase SHA-256 of content is used.
    - `timestamp` string, date-time: When the content occurred. Stored at microsecond precision.
    - `metadata` union: Optional caller JSON stored with the source.
      - object
      - string
      - number
      - boolean
    - `audience` string: Audience slug. Omit it or send project for project-visible memory.
    - `identity` string: Customer id for the author. Its first ingest appearance creates the directory record.
  - `idempotencyKey` string: Replay key for the complete batch.

## Response `200`

Every source in the batch is unchanged.

- IngestBatchResult
  - `projectId` integer, required
  - `ingestionId` string, uuid, required
  - `status` 'queued' | 'completed', required
  - `unchanged` boolean, nullable
  - `items` IngestBatchItemResult[], required
    - `ordinal` integer, required
    - `sourceId` string, required
    - `status` 'queued' | 'completed', required
    - `unchanged` boolean, nullable

## Other responses

- `202`: The batch was accepted and processing was queued.
- `400`: The request is malformed or violates a field constraint. Match behavior on the response code field.
- `401`: missing-api-key: no bearer. malformed-api-key: the header or the key has the wrong shape, or an agent token was sent to a route that accepts keys only. unauthorized: the key is unknown, expired, revoked, or of the kind this route refuses, or the agent token is invalid or expired.
- `402`: out-of-credits: the organization's credits are spent. `data` carries `creditsLeft`, `creditsNeeded` and `resetsOn`. Do not retry: buy credits, or wait for `resetsOn`.
- `403`: project-archived: the project of the key, or the project an agent token names, is archived. Unarchive it in the console to resume. insufficient-scope: the agent token does not carry the scope of the route.
- `409`: The idempotency key was already used with another payload.
- `413`: content-too-large: the batch exceeds 16 MiB of UTF-8 content.
- `429`: The project's monthly cap (project-cap-reached) or the account's spend cap for the billing period (spend-cap-reached) is reached, or the plan's requests per minute are exceeded. The per-minute refusal carries no body.
- `503`: The organization is not ready or background ingestion is disabled.
- `default`: Any other failure uses the same JSON error envelope.

---

[API](https://skmtc.dev/past/apis/past-dev-memory-api.md) · [All operations](https://skmtc.dev/past/apis/past-dev-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/past/apis/past-dev-memory-api/revisions/3ddccc19f0eb?raw)