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

# The record

> What BlobHub records as work happens, by which part of the platform, for how long, and what it does not record.

export const Shot = ({src, alt, caption}) => <Frame caption={caption}>
    <img className="block dark:hidden" src={src} alt={alt} />
    <img className="hidden dark:block" src={src.replace(/\.(png|svg)$/, '.dark.$1')} alt={alt} />
  </Frame>;

Work done on BlobHub is on the record because it happened here; nobody sets anything up in advance. Every run, every
message and every approval is recorded: a workflow's run with each component it passed through, a coding agent's
turns as items in the thread it works in, a person's answer as the item that released a held call. Afterwards,
whoever is accountable can reconstruct what an agent did, in what order and under whose authority, for as long as
each record is [kept](#retention).

## What is recorded, and by which type

Each part of the platform records the work it does, so which records exist depends on what you use.

| Record | Written by | Provided by | Kept |
| - | - | - | - |
| Revisions and their authors | every write that creates or commits one | every blob type with revisions | until deleted |
| Session events | closing and deleting a session, and every change to what it holds | workflow | until the session is deleted |
| Execution events and data | every run, component by component | workflow | 90 days after the run ends, by default |
| Thread items | people, workflows and the worker | workflow sessions | until the session is deleted |
| Schedule fires | every fire | scheduler | 30 days, by default |
| `policy_applied`, `policy_denied` items | the worker, for coding agents | blobhub-worker | with their thread |

A session's event log records the session closing and being deleted, and every change to what it holds: an object
written or deleted, an item posted to a thread, a batch of changes applied to a graph. Creating, editing or reopening
a session writes no event, and a run's start and end are on the run's own log, not the session's. A run's log holds
its flow and component events in order. The data some components attach to an event, such as a model call's request
and response, is kept only when the run's tracing turns on `log_data`, which is off unless the session or the run
sets it.

[Session Events](/blob-types/workflow/workflows/session-events) and
[Execution Events](/blob-types/workflow/workflows/execution-events) define every event type.
[List Session Thread Items](/blob-types/workflow/operations/list-session-thread-items) reads a thread,
[List Executions](/blob-types/scheduler/operations/list-executions) a schedule's fires, and
[List Revisions](/rest-api/blobs/list-revisions) a blob's revisions with their authors. A scheduler has a single
revision that is never committed, so earlier versions of its schedules are not kept; its fires are its history.

<Shot src="/general/images/the-record/revisions.png" alt="A workflow's revision history with authors" caption="Every revision names its author, and every committed one stays readable." />

## Attribution

Most records name who made them. A revision names the account that created it, and committing it does not change
that. A run names who started it, shown as its **Caller** in the debugger, and a thread item names who posted it. A
workflow writes as whoever started its run, so an item a workflow posts names that account. A schedule starts each
run with the standing of whoever created the schedule, so everything a scheduled run writes names the schedule's
author.

Some records name no one. An event says what happened and when, not who did it, and a session records no author of
its own, so who created, closed or deleted a session is not on the record.

An API key has no name of its own: work done with a person's key is signed with that person's name. A
[service account](/general/service-accounts) gives automation its own. A CI runner, a worker or an app's orchestrator
running on one signs every revision it creates, every run it starts and every item it posts as that account, so its
work is never mistaken for a person's. Retiring an account keeps everything it wrote attributed to it.

On a coding agent's thread, everything the worker posts names the worker's identity. Under a `guarded` posture it
also posts a `policy_applied` item before each turn, naming the rules in force, and a `policy_denied` item for every
call a rule refused, naming the rule and the call.

## Reading the record

Every reader pages the same recorded logs, a page at a time with a cursor, so a reader that was not watching still
catches up on everything that happened:

* The [debugger](/general/debugger) lists a session's runs and pages a run's event log, rereading it while the run
  goes on.
* A playground pages its session's event log while its sync runs, so its widgets show what people, runs and agents
  wrote to the session.
* The SDK's `run.events()` returns a run's whole event log, and `run.wait()` can hand each new event to a callback as
  it reads it.
* The REST API lists each record directly: [List Session Events](/blob-types/workflow/operations/list-session-events),
  [List Execution Events](/blob-types/workflow/operations/list-execution-events) and the operations linked under the
  table.

No reader is handed a run's component events as they happen. Each one pages the log, the same way any client of the
API can.

<Shot src="/general/images/the-record/events.png" alt="An execution's event log" caption="Each component a run passes through is on the record, in order." />

## Retention

The table's last column is the longest each record stays. Two records age out under limits whose defaults BlobHub
changes on request, as [Changing a limit](/general/limits#changing-a-limit) explains, and the rest stay until
something deletes them:

* **A finished execution**, with its events and data, is kept for 90 days after it ends by default, under
  `workflow.execution_retention_days`.
* **A schedule's fire record** is kept for 30 days by default, under `scheduler.run_retention_days`.
* **A session**, with its objects, its threads and their items, and its events, is never removed by retention. It
  stays until the session is deleted.
* **A revision** stays until it or its blob is deleted.

A daily sweep removes whatever has passed its limit, and an override can set either limit to `null` to keep forever.
Deleting what holds a record removes the record with it, whatever its age: a thread takes its items, a schedule its
fire records, and a session everything in it, its runs and their events included.
[Retention](/general/limits#retention) has the rules.

## What is not recorded

The record covers the work, not the administration around it.

* **Administrative actions have no audit log.** Adding or removing a member, minting or revoking an API key, storing
  or deleting a credential, and changing who can see an organization or a blob are not recorded as they happen.
  Settings show the state these actions leave behind, not a history of them.
* **Earlier values of what is overwritten.** Writing a session object replaces it, and a draft revision is edited in
  place. The session log records that an object changed, and a commit freezes a revision, but the states in between
  are not kept.
* **No search or analysis.** BlobHub does not search or analyze the record for you. You read it by paging, in the
  debugger, a playground, the SDK or the API, and anything you build on top of it starts from those reads.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.