---
title: "Start a Memory Analysis run"
method: POST
path: "/api/v1/contexts/{context_id}/analyses"
tags: ["analyses"]
---

# Start a Memory Analysis run

`POST /api/v1/contexts/{context_id}/analyses`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/contexts/{context_id}/analyses`
- Auth: none declared

Kick off a background analysis run.

Returns 202 with the new run_id. The pipeline runs in
``asyncio.create_task(run_analysis_task)``; clients poll
``GET /analyses/{run_id}`` for status transitions.

Error mapping (delegated to global handler via custom exceptions):

- 422 ValidationError — context exceeds the #1244 run-size cap
  (checked BEFORE the idempotency guard, so an over-cap context
  with a run already in flight gets 422, not the 409+run_id hint;
  cancel/poll that run via the list endpoint).
- 409 ConflictError  — a prior run is still ``running`` for the
  same (workspace, context). Body carries the existing run_id.
- 422 ValidationError — BYOK key missing (orchestrator's
  pre-flight) OR caller-supplied ``model_id`` does not exist.

## Path parameters

- `context_id` string, uuid, required

## Headers

- `authorization` string, nullable

## Request body

- AnalysisStartRequest: POST /analyses body — same shape as preview (intentional).
  - `from` string, nullable
  - `to` string, nullable
  - `types` string[], nullable
  - `tags` string[], nullable
  - `min_importance` number, nullable
  - `query` string, nullable
  - `model_id` integer, nullable

## Response `202`

Successful Response

- AnalysisStartResponse: 202 Accepted body. Constructed via ``model_validate(analysis)`` so the ORM row's ``id`` column maps to ``run_id`` (matches the issue spec naming) and SQLAlchemy ``Column[datetime]`` ↔ Python ``datetime`` is bridged by Pydantic's ``from_attributes`` rather than manual cast at every call site.
  - `run_id` unknown, required
  - `status` unknown, required
  - `started_at` unknown, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)