API Ryoma: reporting
Usage reports of the organization (org owner and admin; members and viewers only by project)
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/usageAdminUsage grouped over a time range (org owner and admin; other roles can only use groupBy=project)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string (date-time) | yes | |
to | query | string (date-time) | yes | |
groupBy | query | user | project | repo | issue | model | day | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Aggregated rows, highest cost first | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"groupBy": "user",
"total": {
"costUsd": 0,
"tokens": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheCreation": 0
},
"requests": 0,
"sessions": 0
},
"rows": [
{
"costUsd": 0,
"tokens": {},
"requests": 0,
"sessions": 0,
"key": "string",
"label": "string"
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/usage?from=2026-11-01T00:00:00Z&to=2026-11-01T00:00:00Z&groupBy=user" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/resources/usageAdminUsage by Tara resource in the organization (any role)
Sessions that used a Tara resource (skill activation, plugin subagent, or a request with plugin.name or skill.name in the form resource:name) and their cost: attributed directly, and for the whole session. Figures are aggregated by resource, not by person. Tara calls this to show on the resource page and in ph tara stats.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
names | query | string[] | yes | Tara resource names, comma-separated (at most 100) |
days | query | integer | Most recent days, including today |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | One row per name in the order asked, including names with no data yet | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"items": [
{
"name": "string",
"sessions": 0,
"users": 0,
"direct": {},
"sessionTotal": {}
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/resources/usage?names=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/deliveryDelivery metrics per task, joined with AI cost (repos of the projects of the organization)
Tasks read from GitHub through the scm plugin following the Bandum workflow (periodic sync of repos linked to a project) joined with the cost of every session tagged with the task code (forge.issue) in the same repo. Cost per approved task = total cost of all tasks in scope (including rework and abandoned work) divided by the number of approved tasks.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
repo | query | string | owner/repo or repo URL | |
milestone | query | string | Milestone (sprint) name |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Report | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"syncedAt": "2026-11-01T00:00:00Z",
"summary": {
"tasks": 0,
"approved": 0,
"tested": 0,
"rejections": 0,
"costUsd": 0
},
"byLevel": [
{
"level": "string",
"summary": {}
}
],
"tasks": [
{
"repo": "string",
"number": 0,
"key": "string",
"title": "string",
"status": "string",
"level": "string",
"runs": 0,
"rejections": 0,
"approved": false,
"usage": {}
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/delivery" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/delivery/healthDelivery health by project and at-risk tasks (any role of the organization)
By project (a repo not linked to a project goes into the group with an empty project): tasks by status, first-pass approval, rework rate, average time in each status for done tasks, AI cost and the forecast for the remaining work. At-risk tasks use the RYOMA_HEALTH_* thresholds: waiting for testing too long, in progress or sent back too long, sent back many times, AI cost above the baseline for the repo's S/M/L level.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
project | query | string | Project key; leave empty for all projects |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Health by project | application/json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"syncedAt": "2026-11-01T00:00:00Z",
"projects": [
{
"tasks": 0,
"approved": 0,
"tested": 0,
"rejections": 0,
"costUsd": 0,
"project": "string",
"name": "string",
"org": "string",
"todo": 0,
"inProgress": 0,
"review": 0,
"rejected": 0,
"done": 0,
"risks": []
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/delivery/health" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/flowFlow Framework by week - velocity, flow time, efficiency, load, distribution (any role of the organization)
By project or all projects, the last weeks weeks up to now (weeks start Monday 00:00 in the configured time zone; the last week is the current one, counted up to the time of the call). Computed at call time from the current task copy. A metric with no samples is absent (not a fake 0); velocity and load that measure 0 are still present. With from (and optionally to, default today) the range is used instead of weeks: it is rounded down to the Monday of the week of from and the report is computed up to the end of the day to (items done later are not counted), at most 52 weeks. Work types: feature, bug, debt, risk, unknown (tasks missing a type: label). byType only has types that appear in the period and are present in every week of the period.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
project | query | string | Project key; leave empty for all projects (including repos not linked to a project) | |
weeks | query | integer | Most recent weeks, including the current week | |
from | query | string (date) | First day of the range (date, in the configured time zone). When set, it wins over weeks/days. | |
to | query | string (date) | Last day of the range (date, included); default today. Only used together with from. |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Flow report | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"syncedAt": "2026-11-01T00:00:00Z",
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"weeks": [
{
"velocity": 0,
"flowTimeMedianHours": 0,
"flowTimeP85Hours": 0,
"flowEfficiency": 0,
"byType": {},
"week": "string",
"distribution": {}
}
],
"total": {
"velocity": 0,
"flowTimeMedianHours": 0,
"flowTimeP85Hours": 0,
"flowEfficiency": 0,
"byType": {}
},
"wip": {
"total": 0,
"byType": {}
}
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/flow" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/aiAI measurement framework for a project or the whole organization - Utilization, Impact, Cost (any role of the organization)
By project, the last weeks weeks up to now (weeks as in /v1/flow). Computed at call time from the current task copy and telemetry. A metric with no samples is absent (not a fake 0). AI impact is correlation, not causation. An "AI" item is a Done item with at least one model request tagged with the task code (forge.issue, same repo). Impact compares Done items in the period: a group (or a pair of groups for one work type) with fewer than minGroupSize items returns only n and sufficient: false, with no metrics. Cost is summed at the time of each request in the period (not at session start); costPerDoneItem uses the lifetime cost of Done items in the period. Without project the report covers every project of the organization together (repos not linked to a project have no AI telemetry per project and are left out). from/to work as in /v1/flow.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
project | query | string | Project key; leave empty for the whole organization | |
weeks | query | integer | Most recent weeks, including the current week | |
from | query | string (date) | First day of the range (date, in the configured time zone). When set, it wins over weeks/days. | |
to | query | string (date) | Last day of the range (date, included); default today. Only used together with from. |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | AI measurement framework report | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"syncedAt": "2026-11-01T00:00:00Z",
"project": "string",
"org": "string",
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"weeks": [
{
"activeAiUsers": 0,
"doneItems": 0,
"itemsWithAi": 0,
"itemsWithAiShare": 0,
"costUsd": 0,
"reworkCostUsd": 0,
"week": "string"
}
],
"utilization": {
"activeAiUsers": 0,
"doneItems": 0,
"itemsWithAi": 0,
"itemsWithAiShare": 0,
"costUsd": 0,
"reworkCostUsd": 0
},
"impact": {
"minGroupSize": 0,
"total": {
"withAi": {},
"withoutAi": {}
},
"byType": {}
},
"trend": [
{
"month": "string",
"doneItems": 0,
"itemsWithAiShare": 0,
"flowTimeMedianHours": 0
}
],
"cost": {
"attributedUsd": 0,
"reworkCostUsd": 0,
"reworkShare": 0,
"costBeforeFirstRejection": 0,
"costAfterFirstRejection": 0,
"perDoneItem": {
"doneItems": 0,
"costUsd": 0,
"costPerDoneItem": 0
}
}
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/ai" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/insights/overviewOne row per project with the main Flow and AI numbers of a period (any role of the organization)
For the Portal "Insights" overview. Same time range rules as /v1/flow (weeks, or from/to). Projects are sorted by key; repos not linked to a project have no row. risks is the number of at-risk tasks at the time of the call (not per period). A metric with no samples is absent. project keeps one project (404 if the key is not a project of the organization).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
weeks | query | integer | Most recent weeks, including the current week | |
from | query | string (date) | First day of the range (date, in the configured time zone). When set, it wins over weeks/days. | |
to | query | string (date) | Last day of the range (date, included); default today. Only used together with from. | |
project | query | string | Project key; leave empty for all projects of the organization |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Overview | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"syncedAt": "2026-11-01T00:00:00Z",
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"projects": [
{
"project": "string",
"name": "string",
"velocity": 0,
"wip": 0,
"aiCostUsd": 0,
"activeAiUsers": 0,
"risks": 0
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/insights/overview" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/estimate/basisEstimation baseline for sprint planning - flow time and AI cost by S/M/L level (any role of the organization)
By project, the last weeks weeks up to now (weeks as in /v1/flow), from items done in the period. Each level S, M, L is always present. flowTime: p50 and p85 (hours) of flow time (from first entering In progress to Done). cost: mean AI cost and p85 (USD) over done items that have an AI session tagged with the task code (items without a session are not counted). n is the sample count; confidence (none, low under 5 samples, medium under 10, high). A metric with no samples is absent (not a fake 0). Measured by project and level, not by person.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
project | query | string | yes | Project key |
weeks | query | integer | Most recent weeks, including the current week |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Estimation baseline | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"org": "string",
"syncedAt": "2026-11-01T00:00:00Z",
"weeks": 0,
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"levels": [
{
"level": "S",
"done": 0,
"flowTime": {},
"cost": {}
}
],
"done": 0,
"throughputWeeks": 0
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/estimate/basis?project=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/estimateEstimate the AI cost and completion time of a planned batch of tasks (any role of the organization)
A batch is a number of tasks per level (s, m, l) and/or a list of the project's issues (code GH-12, #12 or 12; the level comes from the level label, done tasks are skipped and listed in skipped, issues not in the project are listed in unresolved). Computed with a Monte Carlo simulation (10,000 runs, fixed seed so it is repeatable) over the project's historical data in the last weeks weeks:
- AI cost of the whole batch: each task samples with replacement from historical cost at the same level;
meanis the number of tasks × the mean cost of the level,p50andp85come from the simulation. Levels with too few cost samples are listed inuncoveredand do not add to the total. - Time of the whole batch, in weeks: the batch workload converted by the median flow time of each level (
weights), then simulating the number of weeks to finish when each week completes a random amount drawn from the historical weekly throughput (a week that finishes nothing is also a sample). Assumes throughput and level mix in future weeks match history.
confidence is the lowest of the levels in the batch and the weekly throughput; with few samples it is low or none with warnings. This is a suggestion for sprint planning discussion, not a commitment. Measured by project, not by person.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
project | string | yes | |
weeks | integer | ||
s | integer | ||
m | integer | ||
l | integer | ||
issues | string[] | Issue codes GH-12, #12 or 12; added to s, m, l |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Estimate result | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"project": "string",
"org": "string",
"syncedAt": "2026-11-01T00:00:00Z",
"counts": {
"s": 0,
"m": 0,
"l": 0,
"total": 0
},
"basis": {
"project": "string",
"org": "string",
"syncedAt": "2026-11-01T00:00:00Z",
"weeks": 0,
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"levels": [
{}
],
"done": 0,
"throughputWeeks": 0
},
"cost": {
"meanUsd": 0,
"p50Usd": 0,
"p85Usd": 0,
"uncovered": [
"string"
]
},
"duration": {
"weeks": {
"p50": 0,
"p85": 0
},
"workUnits": 0,
"weights": {}
},
"confidence": "none",
"warnings": [
"string"
],
"unresolved": [
"string"
],
"skipped": [
"string"
]
}Call with curl
curl -X POST "https://ryoma.phillipcli.cloud/v1/estimate" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":"string","weeks":8,"s":0,"m":0}'/v1/insights/reportMonthly report data of the organization or of one project, compared with the period before AI (any role of the organization)
The figures behind the exportable monthly report (Tara renders the PDF and CSV from this): AI cost per approved task (cost over the whole life of the tasks finished in the month, divided by their number), first-time approval rate, rework (share of finished tasks sent back at least once, and share of AI cost spent after a first rejection), flow time, velocity per week, flow efficiency and flow load of the month, compared with the baselineWeeks weeks before the adoption date (baseline; no AI cost there). Without project the figures are pooled over every project of the organization and baseline pools the before-AI period of each project that has an adoption date (flow load of pooled figures is the sum of the projects). projects[].weeks has one row per Monday week touching the month. caveats are the data-quality warnings of each project (the same as /v1/projects/{key}/quality, without names) and the reliability notes of the baseline. The current month is partial (partial: true, ends today). No per-person numbers.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
month | query | string | yes | Month as YYYY-MM (organization time zone); not in the future |
weeks | query | integer | Length of the period before AI, in weeks | |
project | query | string | Project key; leave empty for all projects of the organization |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Report data | application/json · object |
| 400 | Invalid parameters | application/problem+json · object |
| 401 | Missing or invalid token | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | Not found. Also returned for a project that exists but is private and the caller cannot see (never 403, so a private project cannot be discovered) | application/problem+json · object |
| 503 | Tara did not answer the check of which projects the caller can see (private projects). Ryoma never treats this as "sees everything"; retry after the Retry-After header (30 seconds) | application/problem+json · object |
Example response
{
"month": "string",
"from": "string",
"to": "string",
"partial": false,
"org": "string",
"baselineWeeks": 0,
"minSample": 0,
"summary": {
"from": "string",
"to": "string",
"days": 0,
"done": 0,
"tested": 0
},
"projects": [
{
"project": "string",
"name": "string",
"adoptedAt": "string",
"source": "telemetry",
"month": {},
"weeks": []
}
],
"caveats": [
{
"project": "string",
"code": "string",
"message": "string"
}
]
}Call with curl
curl "https://ryoma.phillipcli.cloud/v1/insights/report?month=string" \
-H "Authorization: Bearer $TARA_TOKEN"