---
title: "Append Run Event"
method: POST
path: "/api/v1/runs/{id}/events"
tags: ["Run Internals"]
---

# Append Run Event

`POST /api/v1/runs/{id}/events`

Appends a validated event to the run event log. Intended for trusted internal callers.

## Path parameters

- `id` string, required

## Request body

- RunEvent — Internal RunEvent-compatible JSON payload. The server validates this body by deserializing into the typed RunEvent struct.
  - `id` string, required
  - `ts` string, date-time, required
  - `run_id` string, required
  - `node_id` string, nullable
  - `node_label` string, nullable
  - `stage_id` string, nullable — Stage execution identity, formatted as "{node_id}@{visit}".
  - `parallel_group_id` string, nullable — Durable identity of one execution of a parallel node, formatted as "{node_id}@{visit}".
  - `parallel_branch_id` string — Durable identity of one branch within a parallel execution, in `{parallel_group_id}:{index}` form.
  - `session_id` string, nullable
  - `parent_session_id` string, nullable
  - `tool_call_id` string, nullable — Stable identifier for a tool call, present on agent.tool.* events and other durable events that directly describe the same tool call.
  - `actor` union
    - PrincipalUser
      - `kind` 'user', required
      - `identity` IdpIdentity, required
        - `issuer` string, required
        - `subject` string, required
      - `login` string, required
      - `auth_method` 'github' | 'dev_token', required — Runtime user authentication method.
      - `avatar_url` string, nullable
    - PrincipalWorker
      - `kind` 'worker', required
      - `run_id` string, required
    - PrincipalWebhook
      - `kind` 'webhook', required
      - `delivery_id` string, required
    - PrincipalSlack
      - `kind` 'slack', required
      - `team_id` string, required
      - `user_id` string, required
      - `user_name` string, nullable
    - PrincipalAgent
      - `kind` 'agent', required
      - `session_id` string, nullable
      - `parent_session_id` string, nullable
      - `model` string, nullable
    - PrincipalSystem
      - `kind` 'system', required
      - `system_kind` 'engine' | 'watchdog' | 'timeout', required
  - `event` string, required — Event type discriminator.
  - `properties` object

## Response `200`

Event appended

- AppendEventResponse — Assigned sequence number for an appended event.
  - `seq` integer, required — Assigned event sequence number.

## Other responses

- `400` — Invalid event payload
- `404` — Run not found

---

[API](https://skmtc.net/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.net/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/versions/bee030053823/schema)