Fetch a session's transcript and events

Knoq uses a poll-and-persist model: the AI agent runs in a background workflow and writes every event — user messages, AI responses, tool calls, and status updates — to a durable event log. You read that log by polling this endpoint. There is no streaming or WebSocket connection; your client should poll at a regular interval (the Knoq UI polls every 2.5–5 seconds) until it receives a terminal event. For efficiency, use the sinceEventId cursor on subsequent polls. Passing the ID of the last event you received means the response only includes new events, keeping payloads small as conversations grow.

GET /api/managed-agents/transcript?sessionId=<id>&sinceEventId=<id>

Request

string

required

The ID of the session whose transcript you want to fetch.

string

Optional cursor for delta polling. When provided, the response only includes events that occurred after the event with this ID. Use the id of the last event in the previous response as your cursor. Omit on the first request to receive the full transcript.

Response

string

The session title, derived from the opening message.

string | null

The workflow run ID for the active background execution. null when no workflow is running (the session is idle or terminated).

array

Ordered array of event objects (ascending by occurredAt). Empty when no new events have arrived since sinceEventId.

Show Event object

string

A unique event identifier. Use this as your sinceEventId cursor on the next poll.

string

The event type. Possible values are described in the table below.

object

The full event payload. Structure varies by event type.

string

ISO 8601 timestamp of when this event was recorded.

boolean

true when there are additional events beyond the current page. Poll again — without advancing sinceEventId — to fetch the next page.

boolean

true when Knoq attempted to load an older session’s history but the operation was incomplete (for example, due to a very large event log). The events returned are partial. Continue polling — each subsequent request resumes loading from where the previous one left off.

Event types

Type	Description
`user_message`	A message sent by the user.
`agent_message`	A response produced by the AI agent.
`tool_use`	The agent invoked a connected tool (e.g. searched Slack or queried a GitHub repo).
`tool_result`	The result returned by a tool call.
`status_idle`	The agent has finished processing the current turn and is waiting for a follow-up. This is a terminal event for the current turn.
`status_terminated`	The session has ended permanently (workflow exited or session cancelled).
`error`	An error occurred during processing. The `payload` contains details.

Example

curl "https://knoq.one/api/managed-agents/transcript?sessionId=a3f2c1d4-e5b6-7890-abcd-ef1234567890" \
  -H "Origin: https://knoq.one" \
  -H "Cookie: <your-session-cookie>"

{
  "title": "Summarise the open GitHub issues assigned to me this week.",
  "workflowRunId": "run_01HZ9K2XQTV3N8PMYW46BRCJ5F",
  "events": [
    {
      "id": "evt_01HZ9K2XA1B2C3D4E5F6G7H8I9",
      "type": "user_message",
      "payload": {
        "text": "Summarise the open GitHub issues assigned to me this week."
      },
      "occurredAt": "2025-06-10T14:32:00.123Z"
    },
    {
      "id": "evt_01HZ9K2XB2C3D4E5F6G7H8I9J0",
      "type": "tool_use",
      "payload": {
        "tool": "github_list_issues",
        "input": { "assignee": "me", "state": "open" }
      },
      "occurredAt": "2025-06-10T14:32:01.456Z"
    },
    {
      "id": "evt_01HZ9K2XC3D4E5F6G7H8I9J0K1",
      "type": "tool_result",
      "payload": {
        "tool": "github_list_issues",
        "output": [
          { "number": 142, "title": "Fix pagination in search results" },
          { "number": 138, "title": "Update onboarding copy" }
        ]
      },
      "occurredAt": "2025-06-10T14:32:03.789Z"
    },
    {
      "id": "evt_01HZ9K2XD4E5F6G7H8I9J0K1L2",
      "type": "agent_message",
      "payload": {
        "text": "You have 2 open issues assigned to you this week:\n\n- **#142** Fix pagination in search results\n- **#138** Update onboarding copy"
      },
      "occurredAt": "2025-06-10T14:32:05.012Z"
    },
    {
      "id": "evt_01HZ9K2XE5F6G7H8I9J0K1L2M3",
      "type": "status_idle",
      "payload": {},
      "occurredAt": "2025-06-10T14:32:05.100Z"
    }
  ],
  "hasMore": false,
  "backfillFailed": false
}

Delta polling example

After receiving the response above, pass the last event’s id as sinceEventId on subsequent polls:

curl "https://knoq.one/api/managed-agents/transcript?sessionId=a3f2c1d4-e5b6-7890-abcd-ef1234567890&sinceEventId=evt_01HZ9K2XE5F6G7H8I9J0K1L2M3" \
  -H "Origin: https://knoq.one" \
  -H "Cookie: <your-session-cookie>"

{
  "title": "Summarise the open GitHub issues assigned to me this week.",
  "workflowRunId": "run_01HZ9K2XQTV3N8PMYW46BRCJ5F",
  "events": [],
  "hasMore": false,
  "backfillFailed": false
}

Errors

Status	Meaning
`400`	The `sessionId` parameter is missing, empty, or malformed. The `sinceEventId` cursor, if provided, must be alphanumeric (with hyphens and underscores), up to 128 characters.
`401`	The request is not authenticated. Ensure your session cookie is valid and has not expired.
`404`	No session with the given ID was found for your user and organisation.

Overview

Sessions

Messaging

SCIM Provisioning

Fetch a session's transcript and events

Request

Response

Event types

Example

Delta polling example

Errors

​Request

​Response

​Event types

​Example

​Delta polling example

​Errors

Request

Response

Event types

Example

Delta polling example

Errors