> ## Documentation Index > Fetch the complete documentation index at: https://docs.erstan.com/llms.txt > Use this file to discover all available pages before exploring further. # Read durable run trace > Requires runs:read and the exact API key that created the run. Returns a bounded, redacted page of persisted events, not a live token stream. Treat cursors as opaque and preserve all filters when requesting the next page. ## OpenAPI ````yaml /openapi/public-api.yaml get /v1/public/runs/{runId}/trace openapi: 3.1.0 info: title: Erstan Public Agent API version: 1.4.0 description: >- Start published Erstan agents from external systems and poll for results. API keys carry scopes (`agents:list`, `agents:read`, `agents:write`, `agents:run`, `runs:read`, `tasks:execute`, `documents:read`, `documents:write`, `files:read`, `files:write`). Agent access follows the key creator's current workspace and team permissions. Project and team allowlists (`allowedProjectIds`, `allowedTeamIds`) further restrict task and document and file access. Guarded Agent and Skill draft authoring is available under `/v1/public/authoring` when the workspace capability is enabled. The MCP server at `/v1/mcp` also exposes authoring and task/document/file tools. servers: - url: https://api.erstan.com description: Public endpoint security: - PublicApiKey: [] tags: - name: Authoring description: >- Capability-gated Agent and Skill drafts, history, validation and publication. - name: Agents description: >- Discover and run published agents available to the key creator under their current permissions. - name: Runs description: Read run status and results. - name: MCP description: >- Model Context Protocol server for external clients. Agent Builder tools use `agents:read`, `agents:write`, or both, plus the key creator's live Erstan permissions. Task and content tools also apply project/team allowlists. paths: /v1/public/runs/{runId}/trace: get: tags: - Runs summary: Read durable run trace description: >- Requires runs:read and the exact API key that created the run. Returns a bounded, redacted page of persisted events, not a live token stream. Treat cursors as opaque and preserve all filters when requesting the next page. operationId: getPublicRunTrace parameters: - name: runId in: path required: true schema: type: string - name: cursor in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 default: 100 - name: eventTypes in: query style: form explode: true schema: type: array maxItems: 20 items: type: string maxLength: 100 - name: includePayloads in: query schema: type: boolean default: false - name: payloadMaxChars in: query schema: type: integer minimum: 1600 maximum: 20000 responses: '200': description: >- A durable trace page. Payloads, when requested, remain bounded and redacted. content: application/json: schema: $ref: '#/components/schemas/PublicRunTrace' '400': description: Invalid trace options or cursor. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Run is unavailable to this exact API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PublicRunTrace: type: object required: - runId - status - events - pagination - replayContract properties: runId: type: string status: type: string description: >- Persisted execution status; may differ from the public polling status. events: type: array items: $ref: '#/components/schemas/PublicRunTraceEvent' pagination: type: object required: - limit - hasMore - nextCursor properties: limit: type: integer hasMore: type: boolean nextCursor: type: - string - 'null' replayContract: type: object required: - persistedEventsOnly - chatTokensPersisted - messageReplayEventType properties: persistedEventsOnly: type: boolean const: true chatTokensPersisted: type: boolean const: false messageReplayEventType: type: string const: conversation_item ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' requestId: type: string PublicRunTraceEvent: type: object additionalProperties: true properties: id: type: - string - 'null' sequence: type: - string - 'null' description: Decimal sequence string; do not coerce to a JavaScript number. timestamp: type: - string - 'null' eventType: type: - string - 'null' nodeId: type: - string - 'null' status: type: - string - 'null' occurrenceId: type: - string - 'null' payload: description: Optional bounded redacted event payload. loopPath: description: Optional persisted loop occurrence metadata. ErrorDetail: type: object required: - code - message properties: field: type: string code: type: string message: type: string responses: Unauthorized: description: Missing, invalid, expired, revoked, or inactive API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- The API key lacks scope or the creator lacks current permission for the requested operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: PublicApiKey: type: http scheme: bearer bearerFormat: ers_live API key description: >- Workspace API key created in Erstan Settings. Keys carry scopes (`agents:list`, `agents:read`, `agents:write`, `agents:run`, `runs:read`, `tasks:execute`, `documents:read`, `documents:write`, `files:read`, `files:write`). Agent access follows the key creator's current workspace, team, and agent permissions. Agent draft creation requires `agents:write`; update, validation, and publishing require both `agents:read` and `agents:write`; draft testing also requires `agents:run`. Keys with `tasks:execute` must include at least one allowed project or team (`allowedProjectIds` / `allowedTeamIds`); keys with document or file scopes must include at least one allowed team. Empty allowlists mean no access — the API fails closed. ````