Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

A session is one recorded run of a workflow. It is the only object you create directly — frames, events, and memory entries are derived from it.

​
Lifecycle

created  →  recording  →  stopped  →  sealed
StateMeaning
createdSession exists but capture hasn’t started. Useful when you want to set metadata before pressing record.
recordingFrames and events are streaming in. Session is mutable.
stoppedCapture ended. Indexing has begun. Querying events is allowed but some derived data (memory edges, dataset exports) may still be in progress.
sealedIndexing complete. Session is immutable. Replay, recovery, and export are fully available.
A session typically reaches sealed within seconds of stopped for short runs (under five minutes) and within a minute or two for hour-long runs.

​
Core fields

FieldTypeNotes
idstringFormat: ses_<26 char id>. Stable, unique within workspace.
workflowstringFree-form name. Best practice: stable slug like process_invoice. Used for cross-run grouping in the memory graph.
statusenumOne of the lifecycle values above.
metadataobjectArbitrary JSON. Keep PII out — see masking.
started_attimestampISO 8601 UTC.
stopped_attimestamp | nullNull while recording.
duration_msintegerWall-clock duration.
frame_countintegerTotal captured frames.
event_countintegerTotal extracted events.
actorobject{ id, kind: "human" | "model" | "script" }.

​
Creating a session

const session = await nusomi.sessions.create({
  workflow: "process_invoice",
  metadata: {
    vendor: "Acme",
    amount: 4500,
    queue: "ap-team",
  },
  actor: { id: "alex@nusomi.com", kind: "human" },
});

await session.start();

​
Stopping a session

Stop is idempotent. Calling it twice is safe. 
await session.stop();
// or, by id
await nusomi.sessions.stop("ses_01HXYZ...");

​
Tagging mid-run

You can attach tags as a workflow runs to mark important moments. Tags become anchors in the memory graph. 
await session.tag("submitted_for_approval");
await session.tag("validation_error", { reason: "missing_po" });

​
Listing & filtering

const recent = await nusomi.sessions.list({
  workflow: "process_invoice",
  status: "sealed",
  since: "2026-04-01",
  limit: 50,
});
See the Sessions API reference for the full filter surface.

​
Best practices

  • Use a stable workflow slug. It’s the join key across runs. process_invoice good, Invoice for Acme — May 7 bad.
  • Keep metadata small and structured. Anything you’d want to filter by later goes here. Don’t dump entire request payloads.
  • Don’t log secrets in metadata. Field-level masking only kicks in for captured screen content, not for what you put in metadata yourself.
  • Stop sessions deterministically. Wrap in try / finally so a thrown error doesn’t leave a session recording forever.