Skip to main content
You want every user request, job, or handler invocation to show up as a traceable unit in the dashboard. A run is that unit. A session groups related runs — especially in multi-agent pipelines. When you finish this page, each agent invocation will create a run with a start time, input summary, and completion status.

​
Runs — one invocation, one trace

A run represents a single piece of agent work: processing a user message, handling a webhook, or executing a scheduled job. 
import apie from "./apie.config";

await apie.ready();

await apie.withRun(
  { inputSummary: "Investigate production error rate spike" },
  async (run) => {
    // Your agent logic here
    // run.id is available for withTool, track*, etc.
  },
);

await apie.flush();
await apie.shutdown();
withRun / with_run:
  • Creates a run via POST /v1/runs
  • Executes your callback
  • Marks the run completed or failed
  • Captures errors automatically
  • Flushes the event queue before completing

​
What you’ll see

A new run in the dashboard with your inputSummary, start/end timestamps, and status (completed or failed).

​
HTTP handlers and workers

Wrap request handlers so every incoming request gets its own run. 
export const handleRequest = apie.wrap(
  async (req: Request) => agent.run(await req.json()),
  { inputSummary: (req) => req.url },
);
apie.wrap() is JavaScript-only. In Python, use run_context or with_run.

​
Manual run lifecycle

For fine-grained control, start and complete runs explicitly: 
const run = await apie.runs.start({
  inputSummary: "Investigate production error rate spike",
});

try {
  // agent work
  await apie.runs.complete(run.id, {
    status: "completed",
    metadata: { outputSummary: "Root cause identified." },
  });
} catch (error) {
  await apie.runs.complete(run.id, { status: "failed" });
  throw error;
}
Use sessions when multiple runs belong to one workflow: a release gate pipeline, a support escalation, or an orchestrator delegating to workers. 
await apie.withSession(
  {
    kind: "pipeline",
    inputSummary: "Validate production rollout readiness",
  },
  async (session) => {
    await apie.withRun(
      { sessionId: session.id, inputSummary: "Orchestrator step" },
      async (run) => {
        // Orchestrator work — run.id, session.id available
      },
    );
  },
);
Session kinds:
KindUse when
single_agentOne agent, multiple steps in one session
multi_agentMultiple agents collaborating
pipelineOrchestrator → worker handoffs with ordered steps

​
What you’ll see

A session replay timeline in the dashboard showing all runs and events in order. Open the session replay URL from send-test-event to see an example. If runtime intelligence is enabled for your workspace, Apie can also generate a readable session story after the session has enough evidence. The story adds a summary, grouped timeline, action items, and guardrail recommendations while keeping the raw event timeline available as the source of truth. See Runtime intelligence for how generated stories relate to raw events and guardrail decisions.

​
Next steps

Instrument tool calls

Track what tools your agent invokes inside a run.

Runtime intelligence

Understand generated session summaries, timelines, action items, and recommendations.

Multi-agent pipelines

Model orchestrator → worker handoffs.