Workspaces

Scope your traces, datasets, experiments, judges, behaviors, and billing to a project.

A workspace (also called a "project") is the unit of isolation in Polarity. Every API key, trace, experiment, dataset, judge, behavior, alert, and invoice belongs to exactly one workspace.

Most accounts have one workspace. Create more when you want hard isolation — separating dev / staging / prod, running an audit for an external client, or breaking billing out by team.

Anatomy

{
  id: "ws_abc123",
  name: "prod",
  description: "Production agents — billing rolls up here",
  is_default: false,
  is_favorite: false,
  team_id: "team_...",   # or user_id for personal workspaces
  created_at: "...",
  updated_at: "...",
}

Create

import { Polarity } from "@polarityinc/polarity";
 
const plr = new Polarity();
 
const ws = await plr.workspaces.create({
  name: "prod",
  description: "Production agents — billing rolls up here",
});
 
console.log(ws.id);  // ws_abc123

Pin a session to a workspace

Three ways, in priority order:

1. Constructor: new Polarity({ workspace: "ws_abc123" })
2. Env var: POLARITY_WORKSPACE=ws_abc123
3. API key: keys are workspace-scoped at mint time — the workspace embedded in the key wins if no explicit override.

You can mix — e.g. one global POLARITY_API_KEY (admin scope) plus a per-process POLARITY_WORKSPACE so traces from different services don't bleed into each other.

List and switch

const workspaces = await plr.workspaces.list();
for (const ws of workspaces) {
  console.log(ws.id, ws.name, ws.is_default);
}

Favorites and the default workspace surface first. Pin a workspace in the dashboard sidebar:

await plr.workspaces.favorite(ws.id);
await plr.workspaces.unfavorite(ws.id);

In the dashboard, the workspace switcher is in the top-left of the Polarity sidebar.

Update and delete

await plr.workspaces.update(ws.id, { name: "prod-eu", description: "EU agents" });
await plr.workspaces.delete(ws.id);

The default workspace cannot be renamed or deleted (server returns 400). Workspaces with resources still attached return 409 on delete.

Members

Member management lives in the dashboard at Settings → Members — invite, remove, and manage seats from there. The SDK doesn't expose member-management methods today; this page will gain them when the API does.

Workspace layout

Common patterns:

Polarity's pricing is a flat annual contract per org — workspaces are an organizational tool, not a billing boundary, so split them whenever it makes investigation easier.

When to create a new workspace

• Audit / external client work — keep their traces isolated and billable separately.
• Multi-env deployment — production data shouldn't share dashboards with dev experiments.
• Acquired team / sub-org — give them admin on their own workspace without touching yours.

Don't create a workspace per experiment — that's what spec IDs are for. Workspaces are a heavier boundary, meant to be long-lived.