Batch Get Conversations

curl --request GET \
  --url https://api.example.com/api/conversations

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent": {
      "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"
      },
      "kind": "Agent",
      "tools": {
        "name": "TerminalTool",
        "params": {}
      },
      "mcp_config": {
        "mcpServers": {
          "fetch": {
            "args": [
              "mcp-server-fetch"
            ],
            "command": "uvx"
          }
        }
      },
      "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
      "include_default_tools": [
        "FinishTool",
        "ThinkTool"
      ],
      "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": {
        "cli_mode": true
      },
      "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": "LocalWorkspace"
    },
    "persistence_dir": "workspace/conversations",
    "max_iterations": 500,
    "stuck_detection": true,
    "execution_status": "idle",
    "confirmation_policy": {
      "kind": "NeverConfirm"
    },
    "security_analyzer": {
      "kind": "GraySwanAnalyzer",
      "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"
  }
]

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

api

conversations

Batch Get Conversations

curl --request GET \
  --url https://api.example.com/api/conversations

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent": {
      "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"
      },
      "kind": "Agent",
      "tools": {
        "name": "TerminalTool",
        "params": {}
      },
      "mcp_config": {
        "mcpServers": {
          "fetch": {
            "args": [
              "mcp-server-fetch"
            ],
            "command": "uvx"
          }
        }
      },
      "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
      "include_default_tools": [
        "FinishTool",
        "ThinkTool"
      ],
      "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": {
        "cli_mode": true
      },
      "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": "LocalWorkspace"
    },
    "persistence_dir": "workspace/conversations",
    "max_iterations": 500,
    "stuck_detection": true,
    "execution_status": "idle",
    "confirmation_policy": {
      "kind": "NeverConfirm"
    },
    "security_analyzer": {
      "kind": "GraySwanAnalyzer",
      "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"
  }
]

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Query Parameters

ids

string<uuid>[]

required

Response

(ConversationInfo · object | null)[]

Successful Response

Information about a conversation running locally without a Runtime sandbox.

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>

Guides

Architecture

API Reference

Batch Get Conversations

Query Parameters

Response