---
title: "Get Research Agent session events"
method: GET
path: "/sessions/agents/{sessionId}/events"
tags: ["Research Agent"]
---

# Get Research Agent session events

`GET /sessions/agents/{sessionId}/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

```bash
# 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.

## Path parameters

- `sessionId` string, uuid, required

## Query parameters

- `cursor` string — 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 `200`

Full or incremental reduced session activity.

- GetAgentSessionEventsResponse
  - `sessionId` string, 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.
  - `events` ReducedAgentEvent[], required — Append-only view of the session's activity. Streaming deltas are collapsed into immutable resource snapshots; raw stream events are never returned. Later snapshots retain the same resource ID and receive a new eventId. With no cursor this is the full history; with a cursor it contains only later occurrences.
    - union
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'user_message', required
        - `messageId` string, required
        - `text` string, required
        - `isInitial` boolean, required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'agent_message', required
        - `messageId` string, required
        - `text` string, required — The agent's reply. Contains inline `<citations>…</citations>` markup wrapping one or more comma-separated reference tokens; split them and match each token against `citations[].reference` to resolve it. Strip the markup for display.
        - `citations` object[], required
          - `citationId` string, required — Identifier for this citation within the agent message.
          - `reference` string, nullable, required — The inline citation this entry resolves. It matches, character for character, a single reference token inside the `<citations>…</citations>` markup in the message text (one entry per token, after comma-separated tokens are split). Use it to map inline references in the text to this citation; use the `source` field to identify the underlying source. `null` for citations with no inline reference (e.g. legacy quotes-array or artifact-content citations).
          - `quote` string, required — The passage from the source that supports the message.
          - `source` object, required
            - `title` string, nullable, required — Title of the cited work.
            - `authors` string[], required — Authors of the cited work, in display order.
            - `year` integer, nullable, required — Publication year.
            - `doi` string, nullable, required — Digital Object Identifier (DOI), when available.
            - `url` string, nullable, required — Best available URL for the cited work.
            - `venue` string, nullable, required — Journal, conference, repository, or other publication venue.
        - `suggestedFollowUps` string[], required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'question', required
        - `questionId` string, required
        - `text` string, required
        - `responseFormat` 'text' | 'single_select' | 'multi_select', required
        - `options` object[], nullable, required
          - `optionId` string, required
          - `label` string, required
        - `prefilledText` string, nullable, required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'activity', required
        - `activityId` string, required
        - `status` 'started' | 'completed' | 'failed', required
        - `title` string, required
        - `summary` string, nullable, required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'artifacts_delivered', required
        - `artifacts` PublicAgentArtifact[], required
          - `artifactId` string, required — Opaque identifier for the artifact, stable within a session. Pass it to the download endpoint to retrieve the file. Never a raw storage key.
          - `kind` 'agent-saved-file' | 'agent-delivered-file' | 'prose-export' | 'presentation-export' | 'figure-export' | 'report-asset' | 'report-citation', required — The kind of artifact produced in the session. A delivered file lists once as "agent-delivered-file"; "agent-saved-file" denotes a file the agent saved to its workspace but did not deliver.
          - `format` string, nullable, required — Subtype within the artifact (e.g. "pdf", "docx", "pptx"). For agent files it is the filename extension; null only when the filename has no extension.
          - `filename` string, required — Suggested filename for the downloaded artifact.
          - `contentType` string, nullable, required — MIME type of the artifact, when known.
          - `sizeBytes` number, nullable, required — Size of the artifact in bytes, when known.
          - `createdAt` string, nullable, required — ISO 8601 timestamp of when the artifact was produced, when known.
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'delivered_outputs', required
        - `deliveredOutputs` DeliveredOutputEventSnapshot[], required — Artifacts delivered by this source-history occurrence. This is an immutable metadata snapshot; query the artifacts resource for currently supported download formats.
          - `artifactId` string, required — Opaque identifier for the interactive artifact, stable within a session. Pass it to the artifact content endpoint to retrieve its contents. Never a raw storage key or entity hash.
          - `kind` 'table' | 'prose' | 'presentation' | 'figure', required — The kind of interactive artifact: table, prose, presentation, or figure.
          - `title` string, required — Human-readable title of the artifact.
          - `caption` string, nullable, required — Optional caption describing the artifact.
          - `rowCount` integer, nullable, required — Number of rows for a table artifact; null for non-table kinds.
          - `createdAt` string, nullable, required — ISO 8601 timestamp of when the artifact was delivered, when known.
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'error', required
        - `code` 'agent_timed_out' | 'agent_api_error' | 'agent_failed', required
        - `message` string, required
        - `retryable` boolean, required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'session_idle', required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'session_paused', required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'session_resumed', required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'stop_requested', required
      - object
        - `eventId` string, required — Stable opaque identifier for this immutable public event occurrence.
        - `createdAt` string, nullable, required — ISO 8601 timestamp for the event. Null for historical events without one.
        - `kind` 'session_stopped', required
  - `cursor` string, required — Opaque session-bound checkpoint. Always present. Pass it unchanged as the `cursor` query param on the next poll to receive later event occurrences.
  - `url` string, required — URL to view and continue the session in the Elicit web interface.

## Other responses

- `400` — The cursor is malformed, belongs to another session, or is ahead of the session's current position. Retry without a cursor.
- `401` — Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403` — API access is not available on your current plan. Upgrade to Pro or above to use the API.
- `404` — The Research Agent API is not enabled for this account, or the session does not exist or belongs to another user.
- `429` — Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500` — An unexpected error occurred. Retry after a short delay.

---

[API](https://skmtc.dev/elicit/apis/elicit-api.md) · [All operations](https://skmtc.dev/elicit/apis/elicit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/elicit/elicit-api/revisions/2b42624536e5/schema)