Get project margin
well_get_project_marginRead the revenue, expense, margin and margin rate of one workspace project. The result is one row per accounting currency, with revenue and expense taken from the project's allocation rows on posted (VALIDATED or LOCKED) journal lines, plus its allocation rows on live invoice items whose invoice has no posted journal entry yet; unbooked_revenue and unbooked_expense give that part per currency, and each allocation row says whether it is booked. Revenue counts positive on credit revenue lines and negative on debit revenue lines; expense counts positive on debit expense lines and negative on credit expense lines. The rate is margin divided by revenue, as a percentage with one decimal place; it is null when revenue is zero. A project with no allocations, a deleted project, or a project of another workspace returns an empty margins list. project_name is the live project's display name, or null when the id names no live project of the workspace. monthly is the same revenue, expense and margin grouped per calendar month of the posted entry date (or of the issue date of an unbooked invoice), per currency: it is never truncated, so the months of one currency sum back to its margin row. The result also lists the project's allocations on posted revenue or expense lines and on unbooked invoice items, newest entry first and at most 200 rows, each with its entry date, account name, account type, share, signed amount and currency. allocations_truncated is true when older rows were left out: the margins and the monthly rows still count every row, and the answer says the list shows only the newest rows. budget lists the project's budget cells summed per budget version, fiscal year, fiscal month (1 to 12) and currency, with planned revenue, expense and margin; actual_by_period lists the same actual revenue, expense and margin per fiscal year and fiscal period of the posted entries (period 13 is year-end), so a budget row compares with the actual row of the same fiscal period. Budget rows come from budget versions and are never summed into the actual figures.
Use it to answer "what is the margin on Acme?" after project allocations have been written.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project, from well_list_projects. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| budget | Yes | ||
| margins | Yes | ||
| monthly | Yes | ||
| success | Yes | ||
| allocations | Yes | ||
| project_name | Yes | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| actual_by_period | Yes | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| allocations_truncated | Yes | ||
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |