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 your account, so another tenant's job id 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`.
`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 (3)`, `content must not be empty`). 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 for your account, another tenant's job id also yields `404`.
`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.
User-scoped lookup. Jobs belonging to other tenants are indistinguishable from non-existent ones, both return 404.
Per-item failures live here. Quota, cap, and validation failures appear in the errors array, not as HTTP errors on the import POST. Always read the array to confirm everything landed.

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.