> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontextcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users and organizations

> Segment agent behavior by end user and by customer account. First-class filters, not custom metadata.

Users and organizations are first-class entities in The Context Company. When you attach them on ingest, every analysis surface (patterns, failures, Insight Search, recaps, API, MCP) can be sliced by which user or account is affected.

This is the difference between "the agent is failing" and "the agent is failing for these specific customers on this specific workflow."

## Attaching identity

Set these reserved metadata keys on every run:

* `tcc.userId` — the stable ID of the end user in your system
* `tcc.userName` — display name (optional, requires `tcc.userId`)
* `tcc.orgId` — the ID of their organization / workspace / tenant in your system
* `tcc.orgName` — display name (optional, requires `tcc.orgId`)

Names without IDs are dropped. See [Concepts](/concepts#user-and-organization-identity) for details and framework-specific syntax.

<Note>
  `tcc.orgId` is your customer's ID in your product, not the Context Company platform organization ID.
</Note>

## What the platform does with them

* **Dedicated filters.** Users and organizations are their own filters throughout the dashboard, separate from custom metadata.
* **Native search.** Look up any user or organization by ID or name and jump straight to their runs, sessions, patterns, and failures.
* **First-class API and MCP filters.** `userId` / `external_user_id` and `orgId` / `external_org_id` are top-level parameters on the [REST API](/access-data/api) and [MCP tools](/access-data/mcp).
* **Cohort analyses.** Break down patterns, failures, feedback, cost, and latency by user or organization.

## Analyses this unlocks

Example questions Insight Search can answer once identity is attached:

* Which organizations see the highest failure rate?
* Which users are repeatedly encountering a given pattern or failure?
* Is a failure concentrated in a particular plan, workflow, or customer?
* Which accounts are using a specific tool most, and how often does it fail for them?
* Which enterprise customers had negative feedback this week?
* How does cost per session differ across our top 20 accounts?

Example API calls:

```bash theme={null}
GET /v1/runs?source=prod&range=1d&orgId=acme-corp
GET /v1/sessions?range=2w&userId=user_123
```

Example MCP prompt from your IDE:

> Show me the last 20 runs for `orgId=acme-corp` that errored, and find the most common tool call in them.

## Limitations

* **Retention and churn require your own data.** The Context Company does not currently ingest generic downstream business outcomes (subscription state, product retention, LTV) and cannot claim to correlate agent behavior with them. See [Product gaps](/security/overview) below for the current state.
* Filtering, cohorting, and pattern analysis by user and organization only work on runs where `tcc.userId` / `tcc.orgId` were set. Runs without identity are grouped as anonymous.

## Related

<CardGroup cols={2}>
  <Card title="Conversations and sessions" icon="messages" href="/analyze/conversations-and-sessions">
    Per-user conversation views.
  </Card>

  <Card title="Feedback" icon="thumbs-up" href="/analyze/feedback">
    Feedback attached to a specific user or account.
  </Card>

  <Card title="Insight Search" icon="comment-question" href="/analyze/insight-search">
    Ask questions scoped to a user or organization.
  </Card>

  <Card title="Concepts" icon="cubes" href="/concepts#user-and-organization-identity">
    Reserved identity metadata keys.
  </Card>
</CardGroup>