**Pin** this run's Workspace Snapshots (ADR-0061 s5): keep them past the cold tier's retention TTL, so an investigation is not raced by the GC sweeper.
const url = 'https://example.com/v1/runs/example/snapshots-pin';const options = {method: 'POST'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/runs/example/snapshots-pinThe pin acts on the cold tier’s time bound only. It says nothing about the warm workspace service, which is bounded by space and evicts least-recently- used by design — a warm miss is slower, never wrong, so there is nothing there to protect. Idempotent; recorded with who pinned it and when.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Run id
Responses
Section titled “Responses”Pinned
The cold-tier retention promise over one Run’s Workspace Snapshots (ADR-0061 s5).
ADR-0061 gives Workspace Snapshots two tiers with two policies. The warm workspace service is bounded by space (LRU) and promises nothing — a miss there is slower, never wrong. Object storage is the cold tier, bounded by time, and that is the guarantee a user is given. Everything in this DTO describes the cold tier only; nothing here can or should say anything about the warm tier.
object
The promise has lapsed: this run is terminal, unpinned, and past its window, so its snapshots may already have been swept. Not the same as “gone” — GC is periodic and content is shared, so data often outlives the promise. The honest word for it is expired, not deleted, and a rerun resolves the difference by checking the store.
When this run’s Workspace Snapshots stop being promised (epoch millis).
None while the run is non-terminal: a run that has not settled —
including one suspended on a gate for weeks — is never GC-eligible
regardless of age (ADR-0050), so no expiry applies yet. Also None while
pinned, because a pin holds the window open indefinitely.
A human pinned this run’s Workspace Snapshots — hold them past the window for an investigation.
When it was pinned, epoch millis.
Who pinned it (None when unpinned, or when auth is off).
The retention window in days — what the GC sweeper actually enforces.
Examplegenerated
{ "expired": true, "expires_at": 1, "pinned": true, "pinned_at": 1, "pinned_by": "example", "retention_days": 1}No such run