---
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`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/sessions/agents/{sessionId}/events`
- Auth: HTTP bearer

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`, `methods`, `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`.

### Methods

A `methods` event follows the answer it describes and refers to it with `messageId`. It describes how the answer was produced: an `approach` sentence, a short `summary`, headed `sections`, the `keyJudgments` made along the way, the `searches` that were run, an `evidenceBase` summarizing the cited literature, and any `artifacts` the method produced.

`searches` is a deduplicated list of the queries that were run, in execution order. `source` is a stable corpus key rather than a display label — `academic` (Elicit's academic corpus), `pubmed`, `clinical_trials`, `press_release`, or `web`, with more possible as corpora are added. Together, `searchedAt`, `maxResults`, and the number of entries reproduce the search summary shown in the web interface. `summary` and `evidenceBase` are nullable: an answer can be described without either, and `sections`, `keyJudgments`, `searches` and `artifacts` are empty arrays rather than null when there is nothing to report. `evidenceBase.sourceCount` counts distinct sources, so it is lower than the answer's citation count whenever one source supports several citations. It counts a source as cited when a quote names it or a table row links to it in an artifact the answer produced or referenced — delivery is not the criterion — so for a session with a source-table column it can exceed the count shown on the Methods card in the web interface, which counts only quoted sources.

### Citations

Every citation carries its source inline, including `citationCount`, `fullTextAvailable`, `studyTypeTags`, `journalQuartile`, and `elicitId`. `fullTextAvailable` here reports only what the session itself recorded, so it is frequently `null`; read it from the cited-sources endpoint, which resolves the unknowns. Abstracts are not on this feed — a message is re-emitted with a new `eventId` whenever its citations change, so an abstract would be repeated on each re-emission. Fetch them once from the cited-sources endpoint instead and join on `sourceRef`, which identifies the same source everywhere it appears in a session.

### 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
            - `sourceRef` string, required: Opaque identifier for the underlying source, stable everywhere it appears in a session (message citations, table cells, and the cited-sources endpoint). Use it to deduplicate citations and to join a citation to its entry from the session's cited-sources endpoint, which additionally carries the abstract. Never a raw internal id; do not construct or decode it.
            - `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.
            - `citationCount` integer, nullable, required: Number of works citing this source, when known.
            - `fullTextAvailable` boolean, nullable, required: Whether the source's full text (rather than the abstract alone) is available. Null when the session recorded no verdict — most often on the events feed, which reports only what the session itself recorded. The cited-sources endpoint resolves those unknowns and is the reliable place to read this field.
            - `studyTypeTags` string[], required: Study-design tags for the source, when classified (e.g. "Randomized Controlled Trial", "Meta-Analysis").
            - `journalQuartile` integer, nullable, required: Journal ranking quartile from 1 (highest) to 4, when known.
            - `elicitId` string, nullable, required: Elicit's identifier for the source, when it is in the Elicit corpus.
        - `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` 'methods', required
        - `messageId` string, required: The agent_message this methods record describes. Emitted once per answer, after that message.
        - `approach` string, required: One sentence stating the kind of research performed.
        - `summary` string, nullable, required: A short summary of the method: what was searched, assembled, and compared. Null when the agent recorded no summary.
        - `sections` object[], required: Headed prose sections describing the research process (e.g. "Evidence selection", "Practical translation"), in display order.
          - `heading` string, required
          - `body` string, required
        - `keyJudgments` string[], required: The judgment calls the agent made while producing the answer.
        - `searches` object[], required: The searches behind the answer, deduplicated by corpus and query in execution order.
          - `source` string, required: The corpus searched, as a stable key rather than a display label: "academic" (Elicit's academic corpus), "pubmed", "clinical_trials", "press_release", or "web". Other values are possible as corpora are added.
          - `query` string, required
          - `maxResults` integer, nullable, required: The result cap requested for this query, when one was set.
          - `resultsCount` integer, nullable, required: How many results the query returned, when known.
          - `searchedAt` string, nullable, required: ISO 8601 timestamp of when the query ran, when known.
        - `evidenceBase` object, nullable, required: Coverage of the cited evidence. Null when no source resolved.
          - `sourceCount` integer, required: Number of distinct sources the answer drew on, across its citations and any artifacts it referenced — a source counts as cited when a quote names it or a table row links to it in an artifact the answer produced or referenced, delivered or not. Lower than the citation count when one source supports several citations, and higher than the count on the web interface's Methods card for a session with a source-table column, which counts only quoted sources.
          - `earliestYear` integer, nullable, required
          - `latestYear` integer, nullable, required
        - `artifacts` object[], required: Artifacts the described method produced.
          - `artifactId` string, nullable, required: The delivered artifact this methods record references, matching the id on the artifacts endpoint. Null when the referenced entity was never delivered as an artifact.
          - `title` 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' | 'file' | 'single_select' | 'multi_select', required
        - `options` object[], nullable, required
          - `optionId` string, required
          - `label` string, required
        - `prefilledText` string, nullable, required
        - `questions` object[]: All questions in the form, when the agent requested a multi-question form.
          - `questionId` string, required
          - `text` string, required
          - `responseFormat` 'text' | 'file' | 'single_select' | 'multi_select', required
          - `options` object[], nullable, required
            - `optionId` string, required
            - `label` 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` '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 the session in the Elicit web interface. Only the owner can continue it.

## 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 session does not exist or is not accessible to you for this operation.
- `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 reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-21** `f119b7389237`: 2 warning
  - added the new `file` enum value to the `events/items/oneOf[subschema #4]/questions/items/responseFormat` response property for the response status `200`
  - added the new `file` enum value to the `events/items/oneOf[subschema #4]/responseFormat` response property for the response status `200`
- **2026-10-19** `01e18335df05`: 1 info
  - added the optional property `events/items/oneOf[subschema #4]/questions` to the response with the `200` status
- **2026-10-16** `22847bf7e65d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/changes/sessions/agents/:sessionId/events/get.md)

---

[API](https://skmtc.dev/elicitlabs/apis/elicit-labs-api.md) - [All operations](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elicitlabs/apis/elicit-labs-api/revisions/cbbe29509d04?raw)