---
title: "Compact a session's context"
method: POST
path: "/v3/organizations/{orgId}/sessions/{sessionId}/compact"
tags: ["Sessions"]
---

# Compact a session's context

`POST /v3/organizations/{orgId}/sessions/{sessionId}/compact`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/sessions/{sessionId}/compact`
- Auth: HTTP bearer

Requires run. Summarizes the conversation so far to free context for the turns after it. The response's `outcome` says whether it was queued, applied, or not needed.

<sub>Scope: `run`</sub>

## Response `200`

What the request did.

- SessionCompactionRequested
  - `ok` true, required: Always true on success.
  - `outcome` 'requested' | 'queued' | 'started' | 'already_compacted' | 'credit_exhausted', required: What the request did: requested (the running turn compacts at its next step), queued (the queued turn compacts when it starts), started (a compaction now runs for the finished Session, or one already was), already_compacted (nothing new to compact, or the next turn starts compact), credit_exhausted (no usage left to compact).
  - `status` 'requested': Present when a running or queued turn was asked to compact (outcome requested or queued).
  - `detail` string: Why, when the outcome is not plain: in_progress for a compaction already running, a reason for already_compacted (for example byok_no_model_call) or for credit_exhausted.

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `404`: Resource not found.
- `409`: The Session's state does not allow this now; `error` says why (for example not_terminal while a turn runs).
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.
- `503`: Product writes are disabled.

## Changes

- **2026-10-15** `52a86b8b91b0`: 1 info
  - added the media type `application/json` for the response with the status `200`
- **2026-10-15** `fad7b15a74a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/sessions/:sessionId/compact/post.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)