JavaScript
Objectives
Compact an objective
Summarize a conversation and start a fresh context window on demand, before the threshold forces it.
POST
JavaScript
An objective compacts on its own when its context window crosses the variation’s
The objective stays
Summarization always runs, on the variation’s own model, so a compaction is a billed model call.
That text is the objective’s whole memory of everything before the compaction. When the agent forgets something afterward, the summary dropped it, and
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.
Compact a waiting objective
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 acompactionConfig and it overrides the variation’s, for this compaction only.
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.
instructions is the lever.
When to compact by hand
Automatic compaction fires attriggerThreshold, 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.
Related
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
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.
Optional compaction config override. When not set, uses the variation's compaction_config.
Response
OK
Compact objective response
The new context window created by the compaction