Get full conversation state

POST /api/v1/llm/conversation-state

Returns the complete conversation state. An unknown or non-owned externalId returns 404.

When polling, the absence of an active run does not prove that an accepted or queued request completed. Reconcile the original runId and its outcome before retrying an accepted send.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Build a support conversation the user can return to · Build an assistant that researches the web · Build a signed-in support chat that survives reconnects · Resume a long conversation with a compacted history · Get a customer’s reply and recover an interrupted send · Complete your first support-chat turn · Show one correct chat history as updates arrive · Restore a chat after the connection drops · Let your assistant answer questions about a customer’s calendar · Messages and runs

Request

Responses

Conversation state returned

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

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

Request example

{
  "conversationKey": "example_123"
}

Guide request for Poll conversation state. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-getConversationState#example-cookbook-managed-agents-conversations-build-chat-assistant-04-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
}

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-getConversationState#example-cookbook-managed-agents-conversations-context-management-03-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-getConversationState#example-conversations-getConversationState-response

Response example

{
  "messageHistory": [
    {
      "role": "ROLE_SYSTEM",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "Example text",
          "cachePreferred": true
        }
      ],
      "toolCalls": [
        {
          "id": "example_123",
          "name": "example",
          "status": "TOOL_EXECUTION_STATUS_PENDING",
          "serverId": "example_123",
          "isClientTool": true,
          "description": "example",
          "approvedBy": "example",
          "endReason": "example"
        }
      ],
      "name": "example",
      "timestamp": "2026-09-16T12:00:00Z",
      "messageId": "example_123",
      "annotations": [
        {
          "kind": "ANNOTATION_KIND_URL_CITATION"
        }
      ],
      "sequence": "1",
      "generatedBy": "example",
      "usage": {
        "promptTokens": 1,
        "completionTokens": 1,
        "totalTokens": 1,
        "costEstimate": 1,
        "isByok": true
      },
      "model": "example",
      "generationContext": {
        "languagePreference": "en-US",
        "resolvedSystemPrompt": "Example text",
        "profileId": "example_123",
        "model": "example",
        "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE",
        "profileVersion": 1,
        "fragmentsVersion": 1,
        "profileRenderFailed": true,
        "resolvedPromptHash": "Example text",
        "resolvedUserContext": "Example text"
      },
      "clientContext": {},
      "feedback": [
        {
          "kind": "FEEDBACK_KIND_THUMB",
          "thumbUp": true,
          "reason": "example",
          "ratedBy": "example"
        }
      ],
      "sourceUserMessageId": "example_123",
      "finishReason": "example"
    }
  ],
  "defaultGenerationConfig": {
    "model": "example",
    "models": [
      "example"
    ],
    "systemPrompt": "Example text",
    "modelRoutingFilter": {
      "minContextLength": "1",
      "minMaxCompletionTokens": "1",
      "requiredInputModalities": [
        "example"
      ],
      "requiredOutputModalities": [
        "example"
      ],
      "maxPromptCost": 1,
      "maxCompletionCost": 1,
      "excludeModerated": true,
      "requiredParameters": [
        "example"
      ]
    },
    "provider": {
      "order": [
        "example"
      ],
      "allowFallbacks": true,
      "requireParameters": true,
      "dataCollection": "DATA_COLLECTION_MODE_ALLOW",
      "zdr": true,
      "only": [
        "example"
      ],
      "ignore": [
        "example"
      ],
      "quantizations": [
        "example"
      ],
      "sort": "PROVIDER_SORT_PRICE",
      "enforceDistillableText": true
    },
    "reasoning": {
      "effort": "EFFORT_HIGH",
      "maxTokens": 1,
      "exclude": true,
      "includeReasoningHistory": true
    },
    "usage": {
      "include": true
    },
    "transforms": [
      "example"
    ],
    "tools": [
      {
        "name": "example",
        "description": "example",
        "serverId": "example_123",
        "tags": [
          "example"
        ],
        "documentationUrl": "https://example.com/resource"
      }
    ],
    "toolChoice": {
      "kind": "TOOL_CHOICE_KIND_AUTO",
      "specificToolName": "example"
    },
    "clientTools": [
      {
        "name": "example",
        "description": "example",
        "serverId": "example_123",
        "tags": [
          "example"
        ],
        "documentationUrl": "https://example.com/resource"
      }
    ],
    "toolPolicy": {
      "requireApprovalToolNamePatterns": [
        "example"
      ],
      "requireApprovalServerIds": [
        "example_123"
      ],
      "autoApproveToolNamePatterns": [
        "example"
      ],
      "autoApproveServerIds": [
        "example_123"
      ],
      "approvalMode": "APPROVAL_MODE_MIXED",
      "clientToolMode": "CLIENT_TOOL_MODE_MIXED",
      "approvalTimeoutMs": 1,
      "failOnApprovalTimeoutToolNamePatterns": [
        "example"
      ],
      "stableSortByCallIndexOnTie": true,
      "maxParallelToolCalls": 1,
      "maxToolCallsPerLoop": 1,
      "maxTotalToolCalls": 1,
      "retriableToolNamePatterns": [
        "example"
      ],
      "maxRetries": 1,
      "retryableErrorSubstrings": [
        "example"
      ],
      "nonRetryableErrorSubstrings": [
        "example"
      ],
      "clientToolTimeoutMs": 1,
      "failureMode": "FAILURE_MODE_CONTINUE"
    },
    "temperature": 1,
    "topP": 1,
    "maxOutputTokens": 1,
    "frequencyPenalty": 1,
    "presencePenalty": 1,
    "stopSequences": [
      "example"
    ],
    "seed": "1",
    "responseFormat": {
      "jsonObject": true,
      "schemaName": "example",
      "validate": true,
      "maxValidationRetries": 1,
      "responseHealing": true
    },
    "allowParallelToolCalls": true,
    "topK": 1,
    "repetitionPenalty": 1,
    "logitBias": {},
    "topLogprobs": 1,
    "minP": 1,
    "topA": 1,
    "user": "example",
    "modalities": [
      "MODALITY_TEXT"
    ],
    "plugins": [
      {
        "id": "example_123"
      }
    ],
    "languagePreference": "en-US",
    "timeAware": {
      "includeCurrentTime": true,
      "includeMessageTimestamps": true,
      "includeFileTimestamps": true,
      "timezone": "example",
      "timestampFormat": ""
    },
    "turnContext": {
      "enabled": true,
      "includeToolGuidance": true,
      "format": "minimal"
    },
    "mem0": {
      "enabled": true,
      "searchTopK": 1,
      "searchThreshold": 1,
      "injectAsSystemContext": true,
      "searchQueryOverride": "Example text",
      "enableRerank": true,
      "addMemoriesAsync": true,
      "customExtractionPrompt": "Example text",
      "enableGraph": true,
      "agentIdOverride": "example_123",
      "exposeAsMcpTool": true,
      "includeAssistantMessages": true,
      "injectMemoryTimestamps": true
    },
    "requestTimeoutSeconds": 1,
    "fileResolution": {
      "failureMode": "FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION"
    },
    "clearTools": true
  },
  "settings": {
    "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW",
    "maxLoops": 1,
    "maxParallelTools": 1,
    "mcpServers": [
      {
        "serverId": "example_123",
        "enabled": true,
        "priority": 1,
        "allowlistToolPatterns": [
          "example"
        ],
        "blocklistToolPatterns": [
          "example"
        ]
      }
    ],
    "toolPolicy": {
      "requireApprovalToolNamePatterns": [
        "example"
      ],
      "requireApprovalServerIds": [
        "example_123"
      ],
      "autoApproveToolNamePatterns": [
        "example"
      ],
      "autoApproveServerIds": [
        "example_123"
      ],
      "approvalMode": "APPROVAL_MODE_MIXED",
      "clientToolMode": "CLIENT_TOOL_MODE_MIXED",
      "approvalTimeoutMs": 1,
      "failOnApprovalTimeoutToolNamePatterns": [
        "example"
      ],
      "stableSortByCallIndexOnTie": true,
      "maxParallelToolCalls": 1,
      "maxToolCallsPerLoop": 1,
      "maxTotalToolCalls": 1,
      "retriableToolNamePatterns": [
        "example"
      ],
      "maxRetries": 1,
      "retryableErrorSubstrings": [
        "example"
      ],
      "nonRetryableErrorSubstrings": [
        "example"
      ],
      "clientToolTimeoutMs": 1,
      "failureMode": "FAILURE_MODE_CONTINUE"
    },
    "promptVariables": {
      "example": "value"
    }
  },
  "activeRunId": "example_123",
  "activeRunning": true,
  "contextManagementSettings": {
    "strategy": "CONTEXT_STRATEGY_COMPACTION",
    "compactionConfig": {
      "mode": "COMPACTION_MODE_SYNC",
      "preserveRecent": 1
    },
    "windowingConfig": {
      "maxMessages": 1
    },
    "selectiveExclusionConfig": {
      "excludeToolResults": true,
      "excludeImages": true,
      "excludeFiles": true,
      "excludeReasoning": true
    }
  },
  "compactions": [
    {
      "id": "example_123",
      "startSequence": "1",
      "endSequence": "1",
      "summary": "example",
      "originalTokenCount": 1,
      "summaryTokenCount": 1,
      "modelUsed": "example",
      "createdAt": "2026-09-16T12:00:00Z",
      "status": "COMPACTION_STATUS_PENDING",
      "triggerReason": "COMPACTION_TRIGGER_REASON_THRESHOLD_EXCEEDED"
    }
  ],
  "compactionInProgress": true,
  "totalUsage": {
    "promptTokens": 1,
    "completionTokens": 1,
    "totalTokens": 1,
    "costEstimate": 1,
    "completionTokensDetails": {
      "reasoningTokens": 1,
      "imageTokens": 1,
      "audioTokens": 1
    },
    "promptTokensDetails": {
      "cachedTokens": 1,
      "cacheWriteTokens": 1,
      "audioTokens": 1,
      "videoTokens": 1
    },
    "costDetails": {
      "upstreamInferenceCost": 1,
      "upstreamInferencePromptCost": 1,
      "upstreamInferenceCompletionCost": 1
    },
    "isByok": true
  },
  "externalId": "example_123",
  "conversationKey": "example_123",
  "lastRunStatus": "AGENT_STATUS_ACTIVE"
}

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-getConversationState#example-cookbook-managed-agents-conversations-build-chat-assistant-json-04-response

Response example

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "What can you help me with?"
        }
      ],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    }
  ],
  "activeRunId": "64403669-5989-4ec3-ad9c-d84223f9679f",
  "activeRunning": true
}

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-getConversationState#example-cookbook-managed-agents-conversations-build-chat-assistant-json-05-response

Response example

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "What can you help me with?"
        }
      ],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    },
    {
      "role": "ROLE_ASSISTANT",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "I can assist you with a variety of tasks..."
        }
      ],
      "timestamp": "2026-04-23T22:43:51.653Z",
      "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b",
      "sequence": "2",
      "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f",
      "usage": {
        "promptTokens": 359,
        "completionTokens": 65,
        "totalTokens": 424
      },
      "model": "google/gemini-3.1-flash-lite"
    }
  ],
  "lastRunStatus": "AGENT_STATUS_COMPLETED"
}

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-getConversationState#example-cookbook-managed-agents-conversations-generation-json-02-response

Response example

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "Hello, what can you help me with?"
        }
      ],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    }
  ],
  "activeRunId": "64403669-5989-4ec3-ad9c-d84223f9679f",
  "activeRunning": true
}

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-getConversationState#example-cookbook-managed-agents-conversations-generation-json-03-response

Response example

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "Hello, what can you help me with?"
        }
      ],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    },
    {
      "role": "ROLE_ASSISTANT",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "I can assist you with..."
        }
      ],
      "timestamp": "2026-04-23T22:43:51.653Z",
      "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b",
      "sequence": "2",
      "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f",
      "usage": {
        "promptTokens": 359,
        "completionTokens": 65,
        "totalTokens": 424
      },
      "model": "google/gemini-3.1-flash-lite"
    }
  ],
  "lastRunStatus": "AGENT_STATUS_COMPLETED"
}

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

Section	Stable reference
Get full conversation state	`DOC-MA-conversations-api-getConversationState#overview`
Request	`DOC-MA-conversations-api-getConversationState#request`
Responses	`DOC-MA-conversations-api-getConversationState#responses`

Get full conversation state

/api/v1/llm/conversation-state

Request​

Responses​

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

Guide request for Poll conversation state. Replace example resource identifiers with your own authorized values.​

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

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

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.​

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.​

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.​

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.​

Request

Responses

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

Guide request for Poll conversation state. Replace example resource identifiers with your own authorized values.

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

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

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.

Illustrative response for Poll conversation state. Replace example resource identifiers with your own authorized values.

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.

Illustrative response for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.