Search Events - OpenHands Docs

Search Events

curl --request GET \
  --url https://api.example.com/api/v1/conversation/{conversation_id}/events/search \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://api.example.com/api/v1/conversation/{conversation_id}/events/search"

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.example.com/api/v1/conversation/{conversation_id}/events/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/conversation/{conversation_id}/events/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$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/v1/conversation/{conversation_id}/events/search"

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

	req.Header.Add("X-Access-Token", "<api-key>")

	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/v1/conversation/{conversation_id}/events/search")

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "items": [
    {
      "code": "<string>",
      "detail": "<string>",
      "kind": "<string>",
      "id": "<string>",
      "timestamp": "<string>",
      "parent_id": "<string>"
    }
  ],
  "next_page_id": "<string>"
}

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

GET

/

api

/

v1

/

conversation

/

{conversation_id}

/

events

/

search

Search Events

curl --request GET \
  --url https://api.example.com/api/v1/conversation/{conversation_id}/events/search \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://api.example.com/api/v1/conversation/{conversation_id}/events/search"

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.example.com/api/v1/conversation/{conversation_id}/events/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/conversation/{conversation_id}/events/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$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/v1/conversation/{conversation_id}/events/search"

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

	req.Header.Add("X-Access-Token", "<api-key>")

	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/v1/conversation/{conversation_id}/events/search")

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "items": [
    {
      "code": "<string>",
      "detail": "<string>",
      "kind": "<string>",
      "id": "<string>",
      "timestamp": "<string>",
      "parent_id": "<string>"
    }
  ],
  "next_page_id": "<string>"
}

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

Authorizations

X-Access-Token

string

header

required

Path Parameters

conversation_id

string

required

Query Parameters

kind__eq

enum<string> | null

Available options:

ServerErrorEvent,

ACPToolCallEvent,

Condensation,

CondensationRequest,

CondensationSummaryEvent,

ConversationErrorEvent,

ConversationStateUpdateEvent,

HookExecutionEvent,

LLMCompletionLogEvent,

ActionEvent,

MessageEvent,

AgentErrorEvent,

ObservationEvent,

UserRejectObservation,

SystemPromptEvent,

StreamingDeltaEvent,

TokenEvent,

InterruptEvent,

PauseEvent

timestamp__gte

string<date-time> | null

timestamp__lt

string<date-time> | null

sort_order

enum<string>

default:TIMESTAMP

Enum for event sorting options.

Available options:

TIMESTAMP,

TIMESTAMP_DESC

page_id

string | null

limit

integer

default:100

Required range: x <= 100

Response

Successful Response

items

(ServerErrorEvent · object | ACPToolCallEvent · object | Condensation · object | CondensationRequest · object | CondensationSummaryEvent · object | ConversationErrorEvent · object | ConversationStateUpdateEvent · object | HookExecutionEvent · object | LLMCompletionLogEvent · object | ActionEvent · object | MessageEvent · object | AgentErrorEvent · object | ObservationEvent · object | UserRejectObservation · object | SystemPromptEvent · object | StreamingDeltaEvent · object | TokenEvent · object | InterruptEvent · object | PauseEvent · object)[]

required

Event emitted by the agent server when a server-level error occurs.

This event is used for errors that originate from the agent server itself, such as MCP connection failures, WebSocket errors, or other infrastructure issues. Unlike ConversationErrorEvent which is for conversation-level failures, this event indicates a problem with the server environment.

Show child attributes

next_page_id

string | null

⌘I