Batch Get Conversations

Get a batch of conversations given their ids, returning null for any missing item

GET /api/conversations

Batch Get Conversations

cURL

curl --request GET \
  --url https://api.example.com/api/conversations \
  --header 'X-Session-API-Key: <api-key>'

200

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent": {
      "acp_command": [
        "<string>"
      ],
      "kind": "<string>",
      "llm": {
        "model": "claude-sonnet-4-20250514",
        "api_key": "<string>",
        "base_url": "<string>",
        "api_version": "<string>",
        "aws_access_key_id": "<string>",
        "aws_secret_access_key": "<string>",
        "aws_region_name": "<string>",
        "openrouter_site_url": "https://docs.all-hands.dev/",
        "openrouter_app_name": "OpenHands",
        "num_retries": 5,
        "retry_multiplier": 8,
        "retry_min_wait": 8,
        "retry_max_wait": 64,
        "timeout": 300,
        "max_message_chars": 30000,
        "temperature": 1,
        "top_p": 0.5,
        "top_k": 1,
        "max_input_tokens": 2,
        "max_output_tokens": 2,
        "model_canonical_name": "<string>",
        "extra_headers": {},
        "input_cost_per_token": 1,
        "output_cost_per_token": 1,
        "ollama_base_url": "<string>",
        "stream": false,
        "drop_params": true,
        "modify_params": true,
        "disable_vision": true,
        "disable_stop_word": false,
        "caching_prompt": true,
        "log_completions": false,
        "log_completions_folder": "logs/completions",
        "custom_tokenizer": "<string>",
        "native_tool_calling": true,
        "force_string_serializer": true,
        "reasoning_effort": "high",
        "reasoning_summary": "auto",
        "enable_encrypted_reasoning": true,
        "prompt_cache_retention": "24h",
        "extended_thinking_budget": 200000,
        "seed": 123,
        "safety_settings": [
          {}
        ],
        "usage_id": "default",
        "litellm_extra_body": {}
      },
      "tools": [
        {
          "name": "<string>",
          "params": {}
        }
      ],
      "mcp_config": {},
      "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
      "include_default_tools": [
        "<string>"
      ],
      "agent_context": {
        "skills": [
          {
            "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.",
            "name": "AGENTS.md",
            "type": "repo"
          },
          {
            "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are",
            "name": "flarglebargle",
            "trigger": [
              "flarglebargle"
            ],
            "type": "knowledge"
          }
        ],
        "system_message_suffix": "Always finish your response with the word 'yay!'",
        "user_message_prefix": "The first character of your response should be 'I'"
      },
      "system_prompt_filename": "system_prompt.j2",
      "security_policy_filename": "security_policy.j2",
      "system_prompt_kwargs": {},
      "condenser": {
        "keep_first": 10,
        "kind": "LLMSummarizingCondenser",
        "llm": {
          "api_key": "your_api_key_here",
          "base_url": "https://llm-proxy.eval.all-hands.dev",
          "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"
        },
        "max_size": 80
      },
      "critic": {
        "kind": "AgentFinishedCritic"
      },
      "acp_args": [
        "<string>"
      ],
      "acp_env": {},
      "acp_session_mode": "<string>",
      "acp_prompt_timeout": 1800,
      "acp_model": "<string>"
    },
    "workspace": {
      "working_dir": "<string>",
      "kind": "<string>"
    },
    "persistence_dir": "workspace/conversations",
    "max_iterations": 500,
    "stuck_detection": true,
    "execution_status": "idle",
    "confirmation_policy": {
      "kind": "NeverConfirm"
    },
    "security_analyzer": {
      "kind": "<string>",
      "history_limit": 20,
      "max_message_chars": 30000,
      "timeout": 30,
      "low_threshold": 0.3,
      "medium_threshold": 0.7,
      "api_url": "https://api.grayswan.ai/cygnal/monitor",
      "api_key": "<string>",
      "policy_id": "<string>"
    },
    "activated_knowledge_skills": [
      "<string>"
    ],
    "blocked_actions": {},
    "blocked_messages": {},
    "last_user_message_id": "<string>",
    "stats": {},
    "secret_registry": {
      "secret_sources": {}
    },
    "agent_state": {},
    "hook_config": {
      "pre_tool_use": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ],
      "post_tool_use": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ],
      "user_prompt_submit": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ],
      "session_start": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ],
      "session_end": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ],
      "stop": [
        {
          "matcher": "*",
          "hooks": [
            {
              "command": "<string>",
              "type": "command",
              "timeout": 60,
              "async": false
            }
          ]
        }
      ]
    },
    "title": "<string>",
    "metrics": {
      "model_name": "default",
      "accumulated_cost": 0,
      "max_budget_per_task": 123,
      "accumulated_token_usage": {
        "model": "",
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "cache_read_tokens": 0,
        "cache_write_tokens": 0,
        "reasoning_tokens": 0,
        "context_window": 0,
        "per_turn_token": 0,
        "response_id": ""
      }
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
]

Authorizations

X-Session-API-Key · string · header · required

Query Parameters

ids · string<uuid>[] · required

Response

200

application/json

(ConversationInfo · object | null)[]

Successful Response

Information about a conversation running locally without a Runtime sandbox.

id · string<uuid> · required

Unique conversation ID

agent · ACPAgent · object · required

The agent running in the conversation. This is persisted to allow resuming conversations and check agent configuration to handle e.g., tool changes, LLM changes, etc.

ACPAgent

Agent

Show child attributes

workspace · LocalWorkspace · object · required

Workspace used by the agent to execute commands and read/write files. Not the process working directory.

LocalWorkspace

RemoteWorkspace

Show child attributes

persistence_dir · string | null · default: workspace/conversations

Directory for persisting conversation state and events. If None, conversation will not be persisted.

max_iterations · integer · default: 500

Maximum number of iterations the agent can perform in a single run.

stuck_detection · boolean · default: true

Whether to enable stuck detection for the agent.

execution_status · enum<string> · default: idle

Enum representing the current execution state of the conversation.

Available options: idle, running, paused, waiting_for_confirmation, finished, error, stuck, deleting

confirmation_policy · AlwaysConfirm · object

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

security_analyzer · GraySwanAnalyzer · object

Optional security analyzer to evaluate action risks.

GraySwanAnalyzer

LLMSecurityAnalyzer

Show child attributes

activated_knowledge_skills · string[]

List of activated knowledge skills name

blocked_actions · Blocked Actions · object

Actions blocked by PreToolUse hooks, keyed by action ID

Show child attributes

blocked_messages · Blocked Messages · object

Messages blocked by UserPromptSubmit hooks, keyed by message ID

Show child attributes

last_user_message_id · string | null

Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations).

stats · object

Conversation statistics for tracking LLM metrics

secret_registry · SecretRegistry · object

Registry for handling secrets and sensitive data

Show child attributes

agent_state · Agent State · object

Dictionary for agent-specific runtime state that persists across iterations. Agents can store feature-specific state using string keys. To trigger autosave, always reassign: state.agent_state = {**state.agent_state, key: value}. See https://docs.openhands.dev/sdk/guides/convo-persistence#how-state-persistence-works

hook_config · HookConfig · object

Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks. When set, these hooks are executed at the appropriate points during conversation execution.

Show child attributes

title · string | null

User-defined title for the conversation

metrics · MetricsSnapshot · object

A snapshot of metrics at a point in time.

Does not include lists of individual costs, latencies, or token usages.

Show child attributes

created_at · string<date-time>

updated_at · string<date-time>