Get Research Agent session events

Get a reduced view of a Research Agent session's activity.

Streaming text, thinking, and tool-input deltas are collapsed into complete typed entries. With no cursor, the response contains the full reduced history. Pass the returned cursor unchanged on the next poll to receive immutable event occurrences not observed at that checkpoint.

The public event kinds are user_message, agent_message, question, activity, artifacts_delivered, delivered_outputs, error, session_idle, session_paused, session_resumed, stop_requested, and session_stopped. Internal tool names, sandbox paths, raw tool results, and candidate counters are never returned.

Every event includes a stable eventId and an ISO 8601 createdAt timestamp when available. Events are immutable and append-only. A resource can have several snapshots: for example, an activity may first be started and later completed. Those occurrences share an activityId but have distinct eventId values. Append incremental responses in response order and deduplicate retries by eventId.

The top-level status has exactly the same meaning and value as the list and detail endpoints. Lifecycle facts that are not part of the shared session status vocabulary are represented by explicit events: the agent becomes ready for more input with session_idle, a stop completes with session_stopped, and pause/resume use session_paused/session_resumed.

Polling example

# Full history
curl https://elicit.com/api/v2/sessions/agents/{sessionId}/events \
  -H "Authorization: Bearer elk_live_your_key_here"

# Only event occurrences not observed at the cursor checkpoint
curl "https://elicit.com/api/v2/sessions/agents/{sessionId}/events?cursor={cursor}" \
  -H "Authorization: Bearer elk_live_your_key_here"

Poll every 3–10 seconds while status is processing. The agent is ready for another request when a session_idle event appears and the status returns to completed (idle, awaiting input). A question event indicates that the agent needs input. A session_stopped event confirms that a stop request was processed. If a cursor is rejected, refetch once without a cursor and rebuild local event state.

sessionIdstring uuid required

cursorstring

Opaque cursor from a previous response. When provided, only immutable event occurrences after that checkpoint are returned. Omit it to receive the full history.

Response

Full or incremental reduced session activity.

sessionIdstring required

Unique identifier for the research agent session.

status'processing' | 'pausedForInsufficientQuota' | 'completed' | 'failed' | 'unknown' required

Current status of the session. Uses exactly the same value and semantics as the list and detail endpoints.

cursorstring required

Opaque session-bound checkpoint. Always present. Pass it unchanged as the cursor query param on the next poll to receive later event occurrences.

urlstring required

URL to view and continue the session in the Elicit web interface.

Example response

{
  "events": [
    {
      "artifacts": [
        {
          "createdAt": "2025-06-15T14:30:00.000Z"
        }
      ]
    }
  ]
}

Get Research Agent session events

Polling example

Path parameters

Query parameters

Response

Example response

Changes