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

# Projections

> The four derived read resources — work ledger, adoption, value case, and meter usage — with their parameters and freshness metadata.

Projections are read-only derived views. Each one reports where its numbers
came from and how fresh they are — `meta` carries a `projectionStatus`, a
`sourceCursor` (or an explicit `null` with a status when a cursor is not
available), and an `evidenceStatus` that distinguishes measured data from
insufficient evidence. Update the source records, not the projection.

All four are `GET` operations accepting `Authorization: Bearer oxk_...` or a
web-app session, scoped by `workspace_id`.

## Work ledger — `GET /api/v1/projections/work-ledger`

Aggregated work activity over a time window: tool calls, conversations,
sessions, runs, receipts, decisions, and artifacts, bucketed by time and
broken down by source client and initiative.

| Parameter               | Meaning                                                           |
| ----------------------- | ----------------------------------------------------------------- |
| `granularity`           | `day` (default), `week`, `month`.                                 |
| `from`, `to`            | ISO-8601 window; defaults to the last 14 days.                    |
| `timezone`              | Bucket alignment timezone.                                        |
| `include_source_health` | Anything except `false` includes per-source row counts and notes. |

Response `data`: `buckets[]` (each with counts, per-client and
per-initiative splits), `clients[]`, `initiatives[]`, `totals`, `sources[]`,
`mode` (`aggregated` or `scanned`), `truncated`, and `queryMs`. `meta`
carries `projectionStatus: "derived_work_ledger"` and a `freshness` block;
When `sourceCursor` is `null`, `sourceCursorStatus` explains why a shared
cursor is not available. The API reports that state explicitly.

When `mode` is `scanned`, counts come from bounded reads and may be a floor;
use `truncated` and the freshness metadata when deciding how much confidence
to place in the result.

## Adoption — `GET /api/v1/projections/adoption`

How much a confirmed operating process is actually used.

| Parameter    | Meaning                                 |
| ------------ | --------------------------------------- |
| `process_id` | Required UUID of the operating process. |

Response `data`: `eligiblePopulation`, `targetPathPopulation`,
`behavioralAdoptionRate` (nullable), `selfReportedAdoptionRate` (nullable —
behavioral and self-reported are never merged), `bypassCount`,
`shadowSystemCount`, `confidence`, `limitations[]`, `refreshedAt`. `meta`
reports `evidenceStatus: "measured"` only when there is real behavioral
signal; otherwise `"insufficient_evidence"`.

## Value case — `GET /api/v1/projections/value-case`

The evidence-gated economic view of one process.

| Parameter    | Meaning                                 |
| ------------ | --------------------------------------- |
| `process_id` | Required UUID of the operating process. |

Response `data`: baseline and comparison periods, `realizedOutcomeRefs[]`,
`costMeterEventRefs[]`, `attributionLinkRefs[]`, benefit ranges
(`annualHardBenefit`, `annualCapacityValue`, each `low`/`expected`/`high`),
cost ranges, `roiRange`, `paybackMonthsRange`, `confidence`,
`limitations[]`. Reference arrays stay empty until the underlying outcomes
are independently bound — `meta.evidenceStatus` is
`"realized_outcome_bound"` only when at least one realized outcome exists.

## Meter usage — `GET /api/v1/projections/meter-usage`

Effective usage derived from immutable meter events, with corrections
applied.

| Parameter    | Meaning                                        |
| ------------ | ---------------------------------------------- |
| `from`, `to` | Optional ISO-8601 window (`from` before `to`). |

Response `data`: event counts (raw vs corrected), quantity totals split into
`actualQuantity` and `estimatedQuantity`, per-meter `buckets[]`,
`evidenceStatus` (`measured`, `estimated`, or `insufficient_evidence`),
`limitations[]`, and `billingReady` — a capability flag for billing decisions;
this projection is a usage view, not an invoice.

```bash theme={"dark"}
curl "https://useorgx.com/api/v1/projections/adoption?workspace_id=3d7e4f5a-...&process_id=5e8f2a3b-..." \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

## All operations on these resources

| Operation | Method + path                         | Notes                                                                      |
| --------- | ------------------------------------- | -------------------------------------------------------------------------- |
| Read      | `GET /api/v1/projections/work-ledger` | Windowed activity aggregate.                                               |
| Read      | `GET /api/v1/projections/adoption`    | Per-process adoption.                                                      |
| Read      | `GET /api/v1/projections/value-case`  | Per-process economics, evidence-gated.                                     |
| Read      | `GET /api/v1/projections/meter-usage` | Corrected usage; never billing truth.                                      |
| Write     | Not exposed                           | Projections rebuild from source records; change the sources, not the view. |

## Where the IDs come from

| Field                | Obtain it from                                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `process_id`         | `GET /api/v1/operating-processes` list rows, or the propose flow's returned process                                    |
| `workspace_id`       | `GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id`                                               |
| ref IDs in responses | They point at receipts, meter events, and outcomes; follow them through the [event stream](/docs/api/entities/ledger-event) |

## MCP equivalents

No MCP tool reads these projections today — they are REST-first. The MCP
`orgx_recommend` morning-brief mode reads a separate summary surface.