Skip to main content
POST
JavaScript
An objective compacts on its own when its context window crosses the variation’s triggerThreshold. This endpoint lets you do it early, and lets you steer what the summary keeps. Reach for it before an expensive turn, or when you want a clean window before handing the conversation somewhere new.
Only compact an objective in STATE_WAITING.Compacting a STATE_PENDING or STATE_RUNNING objective returns 200 and permanently stops it. The objective stays STATE_RUNNING forever, produces no further events, and does not respond to cancel. There is no precondition check and no way to recover the run.Check the state first. Unlike continue, which rejects a mid-turn objective with a 400, this endpoint accepts the call and swallows the objective.

Compact a waiting objective

The objective stays STATE_WAITING and remains continuable. A contextWindowCompacted event fires, a new window opens at sequence: 2, and the summary of everything before it is carried forward.
CompactObjectiveResponse declares a contextWindow field. The response body is {} in practice. Read the new window from List context windows instead.

Steer what survives

Pass a compactionConfig and it overrides the variation’s, for this compaction only.
Summarization always runs, on the variation’s own model, so a compaction is a billed model call. toolResultClearing is an optional pre-pass that shrinks what the summarizer has to read; it does not replace it. The summary lands on the new window as previousWindowContinueInstructions, and it populates asynchronously: read the window immediately after compacting and the field is empty, then a few seconds later it holds the summary.
That text is the objective’s whole memory of everything before the compaction. When the agent forgets something afterward, the summary dropped it, and instructions is the lever.

When to compact by hand

Automatic compaction fires at triggerThreshold, a fraction of the model’s maxInputTokens. That is the right default, and most agents never need this endpoint. Manual compaction earns its keep in three places:
  • Before an expensive turn. The next message pulls a large document into the window. Compact first so it fits.
  • At a topic boundary. A support conversation moves from diagnosis to billing. Compact with instructions that keep the diagnosis conclusion and drop the transcript.
  • Before handing off. Another system is about to take the conversation. A compacted window is a smaller, cheaper thing to continue.
Compaction is lossy on purpose. Each one replaces detail with a summary, so compacting on a timer costs you fidelity and a model call for nothing.

List context windows

The new window, its token counts, and the summary it carried in.

Create a variation

triggerThreshold, summarization instructions, and tool result clearing.

Continue an objective

The next turn, which reads the summary you produced.

Get objective diagnostics

How full the window is right now.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required
Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

objectiveId
string
required

The ID of the objective. Supports "external_id:" prefix for external IDs.

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Body

application/json

Compact objective request — triggers compaction on a running objective.

compactionConfig
object

Optional compaction config override. When not set, uses the variation's compaction_config.

Response

OK

Compact objective response

contextWindow
object

The new context window created by the compaction