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

200

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent": {
      "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": 1,
        "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",
        "enable_encrypted_reasoning": true,
        "prompt_cache_retention": "24h",
        "extended_thinking_budget": 200000,
        "seed": 123,
        "safety_settings": [
          {}
        ],
        "usage_id": "default",
        "litellm_extra_body": {}
      },
      "kind": "<string>",
      "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!'"
      },
      "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"
      }
    },
    "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": {},
    "stats": {},
    "secret_registry": {
      "secret_sources": {}
    },
    "agent_state": {},
    "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"
  }
]

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 · Agent · 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.

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

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

title · string | null

User-defined title for the conversation

metrics · MetricsSnapshot · object | null

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>