Skip to main content
GET
/
api
/
v2
/
sessions
/
{id}
/
events
List events
curl --request GET \
  --url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/events \
  --header 'Authorization: Bearer <token>'
Returns a paginated list of events for a session. Use /changes for live tailing; this endpoint is for historical pagination. Auth is optional: supports public shares. Returns a paginated list of TrajectoryEvent objects.

​
Path parameters

​
id
string
required
The session ID.

​
Query parameters

​
page
integer
default:"1"
Page number (1-based).
​
size
integer
default:"50"
Items per page. Maximum: 200.
​
sort
string
default:"timestamp"
Sort order. Options: timestamp, -timestamp.
​
type
string
Filter by event type, e.g. AgentEvent or MetricsUpdateEvent. See Event shape for the full list.

​
Event shape

Every event, on both this endpoint and /changes, is the same envelope: 
{ "type": "AgentEvent", "data": { "...": "..." }, "timestamp": "2026-06-01T15:14:05Z" }
FieldTypeDescription
typestringThe event type (see below).
dataobjectType-specific payload.
timestampstringISO 8601 time the event was recorded.

​
Event types (type)

The most common event types are below. data is an open JSON object whose shape varies by type, so treat this list as representative rather than exhaustive (other types such as DelayAgentStartEvent and AgentRunStatusChangeEvent may appear).
typedataEmitted when
RequestStartEvent{}The session request is received.
RequestStartDispatchedEvent{ "status": "..." }The run is dispatched to a runner.
AgentStartedEvent{}The agent begins executing.
AgentEventa step record (see below)The agent observes, decides, acts, or answers.
MetricsUpdateEvent{ "metrics": {...} }Usage and cost are rolled up. metrics carries steps, total_cost, input_cost, output_cost, and cost_per_model[].
ActiveStateChangeEvent{ "state": "..." }The agent’s active state changes (e.g. idle).
AgentCompletionEvent{ "reason": "..." }The run ends (e.g. "finished").
AgentErrorEvent{ "error": "...", "trace": "...", "info": ... }The run fails; the session moves to failed.

​
Agent activity (AgentEvent.data)

The agent’s step-by-step trace lives inside AgentEvent. Its data is a step record (id, run_id, step_parts, event); the nested event.kind tells you what happened:
event.kindPayload (under data.event)Meaning
message_eventcontent[], caller_idA user or agent message.
observation_eventobservation, a page snapshot keyed by kind (see Observation shapes)What the agent perceived this step.
policy_eventmessage, tool_reqs[]The agent’s decision: its reasoning and the action(s) it chose.
tool_resulttool_req (tool_name, args), resultThe outcome of an action.
answer_eventanswer, contextThe final answer. Same value as /changes answer.
error_eventerror, origin, tool_reqA recoverable error during the step (e.g. a failed or invalid action).
flow_eventflow, originA control-flow signal such as pause, resume, or force_answer, including the ones you trigger via the session controls.
Parsing a stream means switching on the outer type, then for AgentEvent, on data.event.kind: 
{
  "type": "AgentEvent",
  "timestamp": "2026-06-01T15:14:05Z",
  "data": {
    "id": "52747fbd-351a-46f6-a2ae-693251271a4a",
    "run_id": "019dda27-cd8d-434e-b633-96b012df49ad",
    "step_parts": [1],
    "event": {
      "kind": "observation_event",
      "observation": {
        "kind": "web",
        "url": "https://example.com",
        "tabs": ["0"],
        "text": "# Example Domain\nThis domain is for use in illustrative examples...",
        "image": { "type": "s3", "source": "https://.../screenshot-7f3a.png" }
      }
    }
  }
}

​
Observation shapes

observation_event.observation is keyed by kind. The Browser emits one of two shapes, depending on the environment’s mode. web is emitted in visual and multimodal modes: a screenshot plus page metadata.
FieldTypeDescription
kindstring"web".
urlstringCurrent page URL.
titlestringPage title.
tabsarrayOpen tab IDs.
current_tabstringActive tab ID.
imageobjectScreenshot, uploaded and referenced by URL.
textstringVisible page as markdown. Empty in visual, populated in multimodal.
viewport_sizearrayViewport [width, height] in pixels.
page_sizearrayFull page [width, height] in pixels.
scroll_positionarrayScroll offset [x, y] in pixels.
textual_web is emitted in text mode: paginated page text, no screenshot.
FieldTypeDescription
kindstring"textual_web".
urlstringCurrent page URL.
titlestringPage title.
tabsarrayOpen tab IDs.
current_tabstringActive tab ID.
modestring"markdown" or "html".
page_markdownstringFull page rendered as markdown.
page_htmlstringFull page HTML.
text_offsetintegerStart character offset of the current chunk.
chunk_sizeintegerCharacters per chunk.
chunk_numberintegerCurrent chunk, 1-based.
total_chunksintegerTotal chunks for the page.

​
Examples

curl "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/events?size=10" \
  -H "Authorization: Bearer $H_API_KEY"