> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoq.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch a session's transcript and events

> GET /api/managed-agents/transcript — retrieve the full event log for a session, including AI responses and tool calls.

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

<ParamField query="sessionId" type="string" required>
  The ID of the session whose transcript you want to fetch.
</ParamField>

<ParamField query="sinceEventId" type="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.
</ParamField>

## Response

<ResponseField name="title" type="string">
  The session title, derived from the opening message.
</ResponseField>

<ResponseField name="workflowRunId" type="string | null">
  The workflow run ID for the active background execution. `null` when no workflow is running (the session is idle or terminated).
</ResponseField>

<ResponseField name="events" type="array">
  Ordered array of event objects (ascending by `occurredAt`). Empty when no new events have arrived since `sinceEventId`.

  <Expandable title="Event object">
    <ResponseField name="id" type="string">
      A unique event identifier. Use this as your `sinceEventId` cursor on the next poll.
    </ResponseField>

    <ResponseField name="type" type="string">
      The event type. Possible values are described in the table below.
    </ResponseField>

    <ResponseField name="payload" type="object">
      The full event payload. Structure varies by event type.
    </ResponseField>

    <ResponseField name="occurredAt" type="string">
      ISO 8601 timestamp of when this event was recorded.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` when there are additional events beyond the current page. Poll again — without advancing `sinceEventId` — to fetch the next page.
</ResponseField>

<ResponseField name="backfillFailed" type="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.
</ResponseField>

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

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

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

### Delta polling example

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

<CodeGroup>
  ```bash curl theme={null}
  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>"
  ```

  ```json Response theme={null}
  {
    "title": "Summarise the open GitHub issues assigned to me this week.",
    "workflowRunId": "run_01HZ9K2XQTV3N8PMYW46BRCJ5F",
    "events": [],
    "hasMore": false,
    "backfillFailed": false
  }
  ```
</CodeGroup>

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