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, quota, agent cap, or empty content, 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": "monthly write quota reached (25000)"}
  ]
}

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, resuming at the next item), 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, quota reached, empty content, agent cap, and so on.
`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. `monthly write quota reached (25000)`, `agent cap reached (2)`, `content must not be empty`, `end user erased before import`). 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.
Per-item failures live here. Failures found during the import (quota used up mid-batch, agent cap, blank content, end user erased) appear in the errors array. A malformed batch gets 422, and a batch that does not fit the quota 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.