Logs
Timeline of comments and activity attached to a track.
Logs are a timeline attached to a task or goal — for humans leaving comments, and for agents recording activity, without editing the track's own content. Anyone who can access the track can read and append to its logs; logs don't carry a separate ACL. Logs can be deleted by their author, or by the track's creator for moderation.
Use logs for information that belongs in the history of the work rather than in the track's main description: comments, status updates, review results, decisions, and agent notes.
Log kinds
Each log has a kind.
| Kind | Use for |
|---|---|
comment |
Discussion, questions, notes, or shared context |
update |
Work-state reports: what changed, was found, or next |
review |
Verdicts, QA results, approvals, or review outcomes |
comment is the default. Epismo also reserves an internal system kind for platform-generated events; public clients cannot write it.
Every log also has content, optional structured metadata, and an optional idempotencyKey for retry-safe creation. metadata is capped at 16KB once serialized, so long human-readable detail should stay in content.
One track vs activity feed
Reading one track's logs and reading across tracks use the same operation with a different scope.
| Scope | How to read | ACL behavior |
|---|---|---|
| One track | Pass a track reference to epismo_log_list, epismo log list, or GET /v1/logs |
Always checks the track's current ACL |
| Activity feed | Omit the track reference | Uses the ACL snapshot captured when each log was written |
Track-scoped reads are the right choice when you are looking at one task or goal. The activity feed is for "what has been happening?" views across all tracks the caller can currently access, optionally narrowed to one author.
The activity feed is snapshot-based. If someone could see a log when it was written, that log can still appear in their feed after later access changes. A direct read of one track always reflects the track's current ACL.
Authors and visibility
Log authors are resolved for the caller. If the caller can see the author, the log includes that author's userId and authorName. If the author is outside what the caller can see, for example someone who has since left the workspace, both fields are returned as "unknown" rather than exposing the account id.
Filtering by author follows the same rule. If the requested author is not visible to the caller, the result is empty instead of leaking whether that person wrote logs.
Deletion
Authors can delete their own logs. The creator of the parent track can delete any log on that track for moderation. Deleted logs are omitted from future list results.
Retrieval and cost
Retrieval is cursor-based and newest first by default. Use order=asc for chronological replay or, with a cursor, to fetch only logs appended after a known log.
Appending and deleting logs are free. Listing logs costs 1 credit.
When to use
- Add discussion or decisions without rewriting the track description.
- Let agents record what they did, found, or plan to do next.
- Attach review outcomes to the task or goal being reviewed.
- Build an activity feed across work the caller can access.
Use the track's main content for the durable description of the work; use logs for the timeline around that work.