# Identify organizations

Attach the account, workspace, or tenant a user belongs to for org-level analytics.

Organization identification groups users under the account, workspace, or tenant they belong to — so you can see usage, cost, and quality per customer, not just per user.

## Why track organizations?

When you attach an organization id to your telemetry, Brizz can:

- **Roll up activity by account** — usage and cost per customer
- **Compare segments** — behavior across plans, industries, or tiers
- **Spot at-risk accounts** — issues concentrated in a single organization

## Identify an organization

Call `set_organization` / `setOrganization` inside a session. It applies to the turn's spans and propagates to the child spans created within the same context. Only `id` is required; every other field is optional.

For `id`, pass whatever your product already uses as the customer identifier — an account id, customer id, or company id. Brizz builds the per-customer roll-ups from `brizz.organization.*`, so an identifier sent under a name of your own stays a plain attribute and no account view appears.

:::tabs
:::tab[Python]

```python
from brizz import set_organization, start_session

with start_session("session-123"):
    set_organization(id=org.id, name=org.name, plan=org.plan, domain=org.domain)

    reply = agent.run(prompt)
```

:::tab[Node.js]

```typescript
import { startSession, setOrganization } from '@brizz/sdk';

await startSession('session-123', async () => {
  setOrganization({ id: org.id, name: org.name, plan: org.plan, domain: org.domain });

  return agent.run(prompt);
});
```

:::

Each field maps to its own dotted attribute — `brizz.organization.id`, `brizz.organization.name`, `brizz.organization.plan`, `brizz.organization.domain`. The same setter is available on the session object (`session.set_organization(...)` / `session.setOrganization(...)`).

## Extra attributes with traits

For anything beyond the named fields, pass a `traits` record. Each entry becomes `brizz.organization.<key>`; named fields win on key collision. Segment attributes such as tier, industry, or region belong here — that keeps them grouped with the account instead of scattered as top-level attributes.

:::tabs
:::tab[Python]

```python
set_organization(id=org.id, traits={"industry": "fintech", "region": "emea"})
```

:::tab[Node.js]

```typescript
setOrganization({ id: org.id, traits: { industry: 'fintech', region: 'emea' } });
```

:::

## Scoped form

To apply the organization to a single block and reset it on exit, use the scoped wrapper instead of the imperative setter.

:::tabs
:::tab[Python]

```python
from brizz import with_organization

# Runs handle_org with brizz.organization.* on every span created inside it, then resets.
with_organization("org-123", handle_org, name="Acme Inc")
```

:::tab[Node.js]

```typescript
import { callWithOrganization } from '@brizz/sdk';

await callWithOrganization({ id: 'org-123', name: 'Acme Inc', plan: 'enterprise' }, handleOrg);
```

:::

## Best practices

1. **Pair it with a user** — set the user and their organization together so both roll-ups stay in sync.
2. **Use stable IDs** — a durable account id (not a display name) keeps history consistent across renames.

## See also

- [Identify users](/docs/instrument/identify-users.md) — attach the individual end-user.
- [Message IDs](/docs/instrument/message-ids.md) — tag individual replies so you can reference them later.
- [Sessions](/docs/instrument/sessions.md) — the session these attributes attach to.