---
title: "Run (or enqueue) a procedural skill distillation pass"
method: POST
path: "/api/agent/skills/distill"
tags: ["Agent"]
---

# Run (or enqueue) a procedural skill distillation pass

`POST /api/agent/skills/distill`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/api/agent/skills/distill`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

T376/T497. Scans this tenant's entire agent-memory history plus one LLM call per qualifying cluster, so this defaults to ALWAYS async (a job id is returned immediately) unless the caller explicitly opts out with `async: false`.

## Request body

- object
  - `async` boolean: Defaults to true (async job).

## Response `200`

Synchronous distillation result (async=false only).

- object
  - `instancesScanned` integer
  - `clustersFound` integer
  - `qualifyingClusters` integer
  - `distilled` object[]
    - `contextId` integer
    - `clusterKey` string
    - `successCount` integer
    - `created` boolean
  - `skipped` boolean: True when the tenant's LLM spend cap blocked this run.
  - `skipReason` string

## Other responses

- `202`: Enqueued as an async job (default).
- `401`: Missing or invalid credentials.

---

[API](https://skmtc.dev/contextq/apis/contextq-api.md) · [All operations](https://skmtc.dev/contextq/apis/contextq-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextq/apis/contextq-api/revisions/7afc44056a22?raw)