Skip to main content

Compact a conversation

POST 
/api/v1/llm/compact-conversation

Triggers context compaction, summarizing older conversation messages. The trigger estimate can differ from the next request's actual size, especially after changing prompts or tools. Leave room below the model limit and handle context-limit errors.

When configured for asynchronous compaction, this call returns a pending result immediately. Use the returned compactionId to inspect the completed record in conversation-state's compactions array. Compaction can still delay other messages in the conversation; asynchronous acceptance does not guarantee uninterrupted concurrent messaging.

See Context and compaction for strategy selection and outcome handling.

Use this in a guide: Resume a long conversation with a compacted history

Request​

Responses​

Compaction completed

Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.​

Section ID: DOC-MA-conversations-api-compactConversation#example-conversations-compactConversation-request

Request example

{
  "conversationKey": "example_123"
}

Guide request for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-compactConversation#example-cookbook-managed-agents-conversations-context-management-02-request

Request example

{
  "conversationKey": "support-chat-001"
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-MA-conversations-api-compactConversation#example-conversations-compactConversation-response

Response example

{
  "compactionId": "example_123",
  "tokensBefore": 1,
  "tokensAfter": 1,
  "tokensSaved": 1,
  "durationMs": "1",
  "status": "COMPACTION_STATUS_PENDING"
}

Illustrative response for Recipe: compact the older history, then continue the thread. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-compactConversation#example-cookbook-managed-agents-conversations-context-management-json-01-response

Response example

{
  "compactionId": "cmp_a1b2c3d4",
  "tokensBefore": 48211,
  "tokensAfter": 604,
  "tokensSaved": 47607,
  "durationMs": "4120",
  "status": "COMPACTION_STATUS_COMPLETED"
}

Document ID: DOC-MA-conversations-api-compactConversation. Section identities and revisions.

SectionStable reference
Compact a conversationDOC-MA-conversations-api-compactConversation#overview
RequestDOC-MA-conversations-api-compactConversation#request
ResponsesDOC-MA-conversations-api-compactConversation#responses