Batch & status

Batch status

Poll the status of a batch import job, imported and failed counts, plus the per-item errors that explain exactly which memories did not land.

GET /v1/batch/{job_id}

A batch import returns a job_id immediately and processes its memories in the background. Poll this endpoint to watch the job move from pending to completed (or failed). The errors array is the canonical place to discover per-item failures, an end user erased or a key ended while the job waited, that do not surface as HTTP errors on the original import.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key needs the memories:read scope.

Path parameter

Parameter	Type	Required	Description
`job_id`	string	Required	The batch job id returned by the import. Decoded round-trip tolerant, both the `job_`-prefixed hex form and a bare UUID are accepted. Lookup is scoped to the key's project: a job queued by a key of another project (yours or another account's) yields `404`.

This endpoint takes no query parameters and no request body.

Example request

curl https://api.korely.ai/v1/batch/job_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b \
  -H "Authorization: Bearer kor_live_..."

Response

200 OK. The job's lifecycle status with received, imported, and failed counts, plus a per-item error list.

{
  "id": "job_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b",
  "status": "completed",
  "received": 3,
  "imported": 2,
  "failed": 1,
  "errors": [
    {"index": 2, "error": "erased before it was imported"}
  ]
}

Field	Type	Description
`id`	string	Opaque batch job id (`job_` + UUID hex), echoing the job you polled.
`status`	string	Lifecycle status from the job: `pending` · `processing` · `completed` · `failed`. `failed` means an attempt failed: the job is retried automatically (3 attempts in all, from the item where it stopped, never importing an item twice), so it can return to `processing`; it is final when no attempt is left.
`received`	integer	Total number of memory objects in the batch.
`imported`	integer	Count of memories successfully imported so far.
`failed`	integer	Count of memories that failed (see `errors`).
`errors`	array	Per-item failure records, each `{index, error}` where `index` is the position in the submitted memories array and `error` is the failure reason, e.g. `erased before it was imported` (its end user or agent was erased while the job waited), `not imported: the key that queued it was revoked, expired or moved to another project, or the project was archived`, or a rule an old queued item breaks (`content must not be empty or whitespace`). Empty list if no failures.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid API key in the `Authorization` header.
`403`	`forbidden`	The API key lacks the `memories:read` scope.
`404`	`not_found`	Batch job not found. Returned when the path param is neither a `job_`-prefixed hex nor a bare UUID, or when no job with that id exists in the key's project; a job of another project also yields `404`, and so does a finished job deleted after 7 days.
`429`	`rate_limit_exceeded`	Per-tier rate limit hit. Includes a `Retry-After` header; retry shortly.

Notes

Read-only poll, no pagination. One request returns the full job record.
Round-trip tolerant job_id. The path param accepts both the job_-prefixed form and a bare UUID, so whichever shape you stored works.
Project-scoped lookup. Jobs of other projects are indistinguishable from non-existent ones, both return 404. A key confined to some end users reads only the jobs it queued itself: a job another key queued returns 404 too.
Per-item failures live here. Failures found during the import (an end user or agent erased, the key that queued the job ended, a rule an old queued item breaks) appear in the errors array. A malformed batch gets 422, and a batch that does not fit the quota or the agent cap gets 429, at POST time. Always read the array to confirm everything landed.
Kept for 7 days. A finished job (completed, or failed with no attempt left) is deleted 7 days later; after that this endpoint returns 404.

Add a memory, the single-write path the batch import builds on.
List memories, read back what the batch imported.
SDK reference, the typed client across languages.