@kindgi/api 0.1.2 → 0.1.3

package/openapi.json

@@ -224,6 +224,30 @@
           "cancelled"
         ]
       },
+      "RunAgent": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "version",
+          "conversationId"
+        ],
+        "description": "Set on an agent's turn (an agent run, or the turn a flow's agent step started): the agent, the version that ran and the conversation. Absent on other runs, and on turns that ran before Kindgi 0.1.3.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The agent id."
+          },
+          "version": {
+            "type": "string",
+            "description": "The agent version that ran (semver)."
+          },
+          "conversationId": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      },
       "Run": {
         "type": "object",
         "additionalProperties": false,
@@ -299,6 +323,9 @@
             "type": "string",
             "description": "Set on a child run: the node in the parent run that started it."
           },
+          "agent": {
+            "$ref": "#/components/schemas/RunAgent"
+          },
           "publicAccessToken": {
             "type": "string",
             "description": "Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream."
@@ -511,6 +538,9 @@
                   "type": "string",
                   "description": "Set on a child run: the node in the parent run that started it."
                 },
+                "agent": {
+                  "$ref": "#/components/schemas/RunAgent"
+                },
                 "publicAccessToken": {
                   "type": "string",
                   "description": "Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream."
@@ -1356,6 +1386,55 @@
           "expiresAt": {
             "type": "string",
             "format": "date-time"
+          },
+          "decision": {
+            "description": "The reviewer's decision, once one is recorded. Absent while the approval is open, and when it ended without one (it expired, or a timeout escalated it).",
+            "$ref": "#/components/schemas/ApprovalDecisionRecord"
+          }
+        }
+      },
+      "ApprovalDecisionRecord": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "decision",
+          "reviewerId",
+          "reviewerRoleAtDecision",
+          "decidedAt"
+        ],
+        "properties": {
+          "decision": {
+            "type": "string",
+            "enum": [
+              "approve",
+              "reject",
+              "escalate",
+              "withdraw"
+            ]
+          },
+          "decidedBy": {
+            "type": "string",
+            "description": "Who decided, as an actor: `user:<userId>`, the reviewer's user. The run's journal and provenance name the decider the same way. The Kindgi runtime always records it; a deployment whose HITL binding doesn't leaves it out."
+          },
+          "reviewerId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "reviewerRoleAtDecision": {
+            "type": "string",
+            "enum": [
+              "standard",
+              "senior",
+              "admin"
+            ],
+            "description": "Reviewer role class. Hierarchy: standard < senior < admin."
+          },
+          "decidedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "rationale": {
+            "type": "string"
           }
         }
       },
@@ -1452,7 +1531,7 @@
             "type": "string"
           },
           "value": {
-            "description": "Payload passed to the run waitpoint (`RunBinding.completeToken`) when the approval is linked to a suspended run and the decision is `approve` or `reject`."
+            "description": "Payload passed to the run waitpoint (`RunBinding.completeToken`) when the approval is linked to a suspended run and the decision is `approve` or `reject`. Refused (400 `bad-input`) for an agent's tool-call or session gate (`tool-call:pending`, `agent-turn:session-hitl-gate`): those resume on the decision alone."
           }
         }
       },
@@ -3607,6 +3686,11 @@
           "participantId": {
             "type": "string"
           },
+          "projectId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The project the conversation is in: the project of the run that opened it, or `projectId` on open (the tenant's Default project when omitted). Absent on conversations from before Kindgi 0.1.3; those are listed only without a scope."
+          },
           "scope": {
             "type": "object",
             "additionalProperties": true,
@@ -3716,6 +3800,11 @@
             "type": "string",
             "description": "Optional. Defaults to `\"Untitled conversation\"` when omitted."
           },
+          "projectId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The project the conversation is in; `GET /v1/conversations?scopeKind=project&scopeId=…` lists it. A project of the caller's tenant, else `400 bad-input`. Omitted: the tenant's Default project, as for a run."
+          },
           "scope": {
             "type": "object",
             "additionalProperties": true,
@@ -4859,6 +4948,11 @@
           "createdAt": {
             "type": "string",
             "format": "date-time"
+          },
+          "projectId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The project of the record's run. Absent on records from before Kindgi 0.1.3; those are listed only without a scope."
           }
         }
       },
@@ -5040,6 +5134,33 @@
           "createdAt": {
             "type": "string",
             "format": "date-time"
+          },
+          "callUsage": {
+            "type": "object",
+            "description": "Each model call's usage from the cost ledger, by the `callId` in its `model-call` node's attributes. Joined when read: not part of the signed DAG. A signed export includes it, as it stood when signed.",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "usage"
+              ],
+              "properties": {
+                "usage": {
+                  "$ref": "#/components/schemas/ModelCallTokens"
+                },
+                "costUsd": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "durationMs": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "servedModel": {
+                  "type": "string"
+                }
+              }
+            }
           }
         }
       },
@@ -5085,7 +5206,7 @@
         }
       },
       "ExportProvenanceResult": {
-        "description": "Signed exportable bundle. `bundle` is base64 of the exact bytes that were signed (sorted-key canonical JSON, no whitespace); verifiers can pass those bytes directly to `verifyEd25519`. The bundle body itself includes `bundleSchemaVersion`, `runId`, `tenantId`, `dag: { nodes, edges }`, `messages?` (if requested), etc. See `canonicalization` for the deterministic serialization algorithm.",
+        "description": "Signed exportable bundle. `bundle` is base64 of the exact bytes that were signed (sorted-key canonical JSON, no whitespace); verifiers can pass those bytes directly to `verifyEd25519`. The bundle body itself includes `bundleSchemaVersion`, `runId`, `tenantId`, `dag: { nodes, edges }`, `messages?` (if requested), `callUsage?` (the usage of the model calls, from the cost ledger), etc. See `canonicalization` for the deterministic serialization algorithm.",
         "type": "object",
         "additionalProperties": false,
         "required": [
@@ -5110,7 +5231,7 @@
           },
           "bundleSchemaVersion": {
             "type": "string",
-            "description": "Semver for the shape of the bundle body. Currently `1.0.0`."
+            "description": "Semver for the shape of the bundle body. Currently `1.1.0`, which adds `callUsage`: each model call's usage from the cost ledger, by call id, as it stood when signed."
           },
           "algorithm": {
             "type": "string",
@@ -6175,7 +6296,13 @@
           "day",
           "month",
           "tenant",
-          "conversationId"
+          "conversationId",
+          "model",
+          "servedModel",
+          "projectId",
+          "orgId",
+          "rootRunId",
+          "flowId"
         ]
       },
       "CostRecord": {
@@ -6240,6 +6367,184 @@
             "type": "object",
             "additionalProperties": true,
             "description": "Free-form filter/display tags — never counters."
+          },
+          "callId": {
+            "type": "string",
+            "description": "A model call's id (`category` `llm.inference`); its provenance `model-call` node carries it too."
+          },
+          "projectId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "rootRunId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The root of the record's run tree (a flow run, for its agent turns)."
+          },
+          "parentRunId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agentVersion": {
+            "type": "string"
+          },
+          "flowId": {
+            "type": "string",
+            "description": "The flow of the run tree's root."
+          },
+          "nodeId": {
+            "type": "string",
+            "description": "The step that made the call."
+          },
+          "step": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "The turn's step number."
+          },
+          "purpose": {
+            "type": "string",
+            "description": "What the call was for, beyond the turn's own model step: `guardrail-judge:<guardrail id>`."
+          },
+          "model": {
+            "type": "string",
+            "description": "The model actually called."
+          },
+          "servedModel": {
+            "type": "string",
+            "description": "The exact model version the vendor reported (vendors alias)."
+          },
+          "fallback": {
+            "type": "boolean",
+            "description": "The router picked a fallback provider for the turn."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "failed"
+            ],
+            "description": "`ok`: the provider answered. `failed`: the call threw."
+          },
+          "usage": {
+            "$ref": "#/components/schemas/ModelCallTokens"
+          },
+          "durationMs": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "finishReason": {
+            "type": "string"
+          },
+          "providerRequestId": {
+            "type": "string",
+            "description": "The vendor's id for the request."
+          },
+          "attempts": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "HTTP attempts the call took, the client's retries included."
+          },
+          "error": {
+            "$ref": "#/components/schemas/ModelCallError"
+          },
+          "rawUsage": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "provider",
+              "model",
+              "usage"
+            ],
+            "description": "The vendor's own usage object, exactly as it reported it. Only with `include=rawUsage`.",
+            "properties": {
+              "provider": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "usage": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          }
+        }
+      },
+      "ModelCallTokens": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "promptTokens",
+          "completionTokens"
+        ],
+        "description": "The call's tokens. `promptTokens` / `completionTokens` are the totals; `cacheReadTokens` / `cacheWriteTokens` are parts of `promptTokens`, `reasoningTokens` of `completionTokens`, present when the provider reports them.",
+        "properties": {
+          "promptTokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "completionTokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "cacheReadTokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "cacheWriteTokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "reasoningTokens": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "ModelCallError": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "message"
+        ],
+        "description": "Why a model call failed (`status: failed`).",
+        "properties": {
+          "message": {
+            "type": "string"
+          }
+        }
+      },
+      "CostTokenTotals": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "prompt",
+          "completion",
+          "cacheRead",
+          "cacheWrite",
+          "reasoning"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "completion": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "cacheRead": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "cacheWrite": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "reasoning": {
+            "type": "integer",
+            "minimum": 0
           }
         }
       },
@@ -6271,7 +6576,8 @@
         "required": [
           "key",
           "count",
-          "totalUsd"
+          "totalUsd",
+          "tokens"
         ],
         "properties": {
           "key": {
@@ -6291,6 +6597,9 @@
           "totalUsd": {
             "type": "number",
             "minimum": 0
+          },
+          "tokens": {
+            "$ref": "#/components/schemas/CostTokenTotals"
           }
         }
       },
@@ -6301,6 +6610,7 @@
           "groups",
           "totalUsd",
           "totalRecords",
+          "tokens",
           "timeRange",
           "groupBy"
         ],
@@ -6319,6 +6629,9 @@
             "type": "integer",
             "minimum": 0
           },
+          "tokens": {
+            "$ref": "#/components/schemas/CostTokenTotals"
+          },
           "timeRange": {
             "type": "object",
             "additionalProperties": false,
@@ -7329,7 +7642,7 @@
         }
       },
       "WhoamiResult": {
-        "description": "Introspection of the caller's current authentication context. Always carries `tenantId` and `scopes` (empty for static bearer tokens), plus `userId` when the token carries one; session-token callers additionally see `sessionId`, `providerId`, and `expiresAt`. `user` is the caller's directory record, present when the deployment wires an identity directory and it knows the `userId`. `reviewerRole` is set when the token carries a reviewer role — clients can use it to gate reviewer-only UI (the approvals surface) without a second round trip.",
+        "description": "Introspection of the caller's current authentication context. Always carries `tenantId` and `scopes` (empty for static bearer tokens), plus `userId` when the token carries one; session-token callers additionally see `sessionId`, `providerId`, and `expiresAt`. `user` is the caller's directory record, present when the deployment wires an identity directory and it knows the `userId`. `reviewerRole` is set when the caller is a reviewer — its token carries a reviewer role, or its user is a registered reviewer — so clients can gate reviewer-only UI (the approvals surface) without a second round trip.",
         "type": "object",
         "additionalProperties": false,
         "required": [
@@ -10697,6 +11010,29 @@
           }
         }
       },
+      "RunTreeUsage": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "calls",
+          "costUsd",
+          "tokens"
+        ],
+        "description": "The model calls of the run tree (this run and every run it started) that the cost ledger had recorded when this run finished: a child run still running then isn't in it. `calls` counts failed calls too. Absent when the runtime records no usage.",
+        "properties": {
+          "calls": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "costUsd": {
+            "type": "number",
+            "minimum": 0
+          },
+          "tokens": {
+            "$ref": "#/components/schemas/CostTokenTotals"
+          }
+        }
+      },
       "FinishedRun": {
         "type": "object",
         "additionalProperties": false,
@@ -10753,6 +11089,9 @@
           "completedAt": {
             "type": "string",
             "format": "date-time"
+          },
+          "usage": {
+            "$ref": "#/components/schemas/RunTreeUsage"
           }
         }
       },
@@ -11149,7 +11488,7 @@
             }
           },
           "400": {
-            "description": "Malformed cursor or filter.",
+            "description": "Malformed cursor, filter or scope.",
             "content": {
               "application/json": {
                 "schema": {
@@ -11192,6 +11531,25 @@
             "required": false,
             "description": "Opaque cursor from a prior response. Absent → first page."
           },
+          {
+            "name": "scopeKind",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/ScopeKind"
+            },
+            "required": false,
+            "description": "Optional scope discriminator. If absent, no scope filter is applied."
+          },
+          {
+            "name": "scopeId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "description": "Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (tenant is implicit from the session). Malformed combinations return 400 scope-invalid."
+          },
           {
             "name": "parentRunId",
             "in": "query",
@@ -11211,6 +11569,16 @@
             "required": false,
             "description": "When true, only runs that are not a child of another run."
           },
+          {
+            "name": "agentId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "description": "Only this agent's turns, at any version. Turns that ran before Kindgi 0.1.3 don't name their agent and aren't matched."
+          },
           {
             "name": "include",
             "in": "query",
@@ -11249,6 +11617,16 @@
               }
             }
           },
+          "400": {
+            "description": "`runId` is not a run id (a UUID).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WireError"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Missing / malformed / expired / revoked bearer token.",
             "content": {
@@ -11505,6 +11883,16 @@
               }
             }
           },
+          "400": {
+            "description": "`runId` is not a run id (a UUID).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WireError"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Missing / malformed / expired / revoked bearer token.",
             "content": {
@@ -11574,6 +11962,16 @@
               }
             }
           },
+          "400": {
+            "description": "`runId` is not a run id (a UUID).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WireError"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Missing / malformed / expired / revoked bearer token.",
             "content": {
@@ -11642,6 +12040,16 @@
               }
             }
           },
+          "400": {
+            "description": "`runId` is not a run id (a UUID).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WireError"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Missing / malformed / expired / revoked bearer token.",
             "content": {
@@ -11704,6 +12112,16 @@
               }
             }
           },
+          "400": {
+            "description": "`runId` is not a run id (a UUID).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WireError"
+                }
+              }
+            }
+          },
           "401": {
             "description": "Missing / malformed / expired / revoked bearer token.",
             "content": {
@@ -12575,7 +12993,7 @@
             }
           },
           "400": {
-            "description": "Malformed query parameter.",
+            "description": "Malformed query parameter or scope.",
             "content": {
               "application/json": {
                 "schema": {
@@ -12595,7 +13013,7 @@
             }
           },
           "403": {
-            "description": "Token lacks a reviewer role or asked for a tier above the caller.",
+            "description": "The caller isn't a reviewer, or asked for a tier above its own.",
             "content": {
               "application/json": {
                 "schema": {
@@ -12605,7 +13023,7 @@
             }
           }
         },
-        "description": "Requires the token to carry a `reviewerRole`. Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin).",
+        "description": "Requires a reviewer: a token that carries a `reviewerRole`, or whose user is a registered reviewer (the roster gives the role). Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin). `scopeKind`/`scopeId` narrow to one project's approvals, or every project's in an org; approvals from before Kindgi 0.1.3 have no project and are listed only without a scope.",
         "parameters": [
           {
             "name": "limit",
@@ -12628,6 +13046,25 @@
             "required": false,
             "description": "Opaque cursor from a prior response. Absent → first page."
           },
+          {
+            "name": "scopeKind",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/ScopeKind"
+            },
+            "required": false,
+            "description": "Optional scope discriminator. If absent, no scope filter is applied."
+          },
+          {
+            "name": "scopeId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "description": "Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (tenant is implicit from the session). Malformed combinations return 400 scope-invalid."
+          },
           {
             "name": "status",
             "in": "query",
@@ -12693,7 +13130,7 @@
             }
           },
           "403": {
-            "description": "Token lacks a reviewer role.",
+            "description": "The caller isn't a reviewer.",
             "content": {
               "application/json": {
                 "schema": {
@@ -12713,7 +13150,7 @@
             }
           }
         },
-        "description": "Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4).",
+        "description": "Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4). A decided approval carries its `decision`: what the reviewer decided, why, and who (`decidedBy`, `user:<userId>`).",
         "parameters": [
           {
             "name": "approvalId",
@@ -12812,7 +13249,7 @@
             }
           }
         },
-        "description": "Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes.",
+        "description": "Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes, with `{ decided, rationale?, decidedBy, approvalId }`: the run's journal records who decided which approval (`decidedBy` is `user:<userId>`).",
         "parameters": [
           {
             "name": "approvalId",
@@ -13214,7 +13651,7 @@
             }
           },
           "403": {
-            "description": "Token lacks a reviewer role.",
+            "description": "The caller isn't a reviewer.",
             "content": {
               "application/json": {
                 "schema": {
@@ -15513,7 +15950,7 @@
             }
           },
           "400": {
-            "description": "Malformed query parameter.",
+            "description": "Malformed query parameter or scope.",
             "content": {
               "application/json": {
                 "schema": {
@@ -15533,7 +15970,7 @@
             }
           }
         },
-        "description": "Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`.",
+        "description": "Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`, and `scopeKind`/`scopeId` for one project's conversations, or every project's in an org. Conversations from before Kindgi 0.1.3 have no project and are listed only without a scope.",
         "parameters": [
           {
             "name": "limit",
@@ -15556,6 +15993,25 @@
             "required": false,
             "description": "Opaque cursor from a prior response. Absent → first page."
           },
+          {
+            "name": "scopeKind",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/ScopeKind"
+            },
+            "required": false,
+            "description": "Optional scope discriminator. If absent, no scope filter is applied."
+          },
+          {
+            "name": "scopeId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "description": "Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (tenant is implicit from the session). Malformed combinations return 400 scope-invalid."
+          },
           {
             "name": "agentId",
             "in": "query",
@@ -15638,7 +16094,7 @@
             }
           }
         },
-        "description": "Pins `(agentId, agentVersion)` at open time. `title` defaults to `\"Untitled conversation\"` when omitted; `scope` accepts arbitrary JSON.",
+        "description": "Pins `(agentId, agentVersion)` at open time. `title` defaults to `\"Untitled conversation\"` when omitted; `projectId` puts it in a project (lists filter by it; omitted, the Default project); `scope` accepts arbitrary JSON.",
         "parameters": [
           {
             "name": "Idempotency-Key",
@@ -17317,7 +17773,7 @@
             }
           },
           "400": {
-            "description": "Malformed cursor or `createdAfter` timestamp.",
+            "description": "Malformed cursor, `createdAfter` timestamp or scope.",
             "content": {
               "application/json": {
                 "schema": {
@@ -17337,7 +17793,7 @@
             }
           }
         },
-        "description": "Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`.",
+        "description": "Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`, and `scopeKind`/`scopeId` for one project's records, or every project's in an org (records from before Kindgi 0.1.3 have no project and are listed only without a scope).",
         "parameters": [
           {
             "name": "limit",
@@ -17360,6 +17816,25 @@
             "required": false,
             "description": "Opaque cursor from a prior response. Absent → first page."
           },
+          {
+            "name": "scopeKind",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/ScopeKind"
+            },
+            "required": false,
+            "description": "Optional scope discriminator. If absent, no scope filter is applied."
+          },
+          {
+            "name": "scopeId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            },
+            "required": false,
+            "description": "Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (tenant is implicit from the session). Malformed combinations return 400 scope-invalid."
+          },
           {
             "name": "runId",
             "in": "query",
@@ -19264,7 +19739,7 @@
             }
           }
         },
-        "description": "Cursor-paginated. Filters (all AND): `runId`, `agentId`, `conversationId`, `category`, `providerId`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — LLM inference, tool invocation, storage write, sandbox execution, etc.",
+        "description": "Cursor-paginated. Filters (all AND): `runId` (with `includeDescendants`, its whole subtree), `rootRunId`, `agentId`, `conversationId`, `category`, `providerId`, `model`, `servedModel`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — a model call (`category` `llm.inference`: one record per call, with its model, usage and what the vendor said about it), tool invocation, storage write, sandbox execution, etc. `include=rawUsage` adds each model call's usage as the vendor reported it.",
         "parameters": [
           {
             "name": "limit",
@@ -19334,6 +19809,44 @@
             "required": false,
             "description": "Filter records to this provider id (exact match)."
           },
+          {
+            "name": "model",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "Filter model calls to this model, the one actually called (exact match)."
+          },
+          {
+            "name": "servedModel",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "Filter model calls to the exact model version the vendor reported (exact match)."
+          },
+          {
+            "name": "rootRunId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "description": "Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started."
+          },
+          {
+            "name": "includeDescendants",
+            "in": "query",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            },
+            "required": false,
+            "description": "With `runId`: the run's records and those of every run it started, at any depth. `true` or `false` (default)."
+          },
           {
             "name": "from",
             "in": "query",
@@ -19352,7 +19865,7 @@
               "format": "date-time"
             },
             "required": false,
-            "description": "ISO 8601 timestamp; records with `occurredAt <= to`. Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window)."
+            "description": "ISO 8601 timestamp; records with `occurredAt < to` (exclusive). Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window)."
           },
           {
             "name": "scopeKind",
@@ -19382,6 +19895,18 @@
             },
             "required": false,
             "description": "Default `true`. `false` = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/...)."
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "rawUsage"
+              ]
+            },
+            "required": false,
+            "description": "Extra fields, comma-separated. `rawUsage`: each model call's usage object exactly as the vendor reported it."
           }
         ],
         "security": [
@@ -19439,6 +19964,18 @@
             },
             "required": true,
             "description": "CostRecordId — opaque string identifier chosen by the binding."
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "rawUsage"
+              ]
+            },
+            "required": false,
+            "description": "Extra fields, comma-separated. `rawUsage`: each model call's usage object exactly as the vendor reported it."
           }
         ],
         "security": [
@@ -19487,7 +20024,7 @@
             }
           }
         },
-        "description": "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId + ?inherit` narrow the aggregate to a specific scope — reconciles byte-for-byte with the same scoped `/records` list.",
+        "description": "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. Each group, and the total, carries its cost and its token sums (`tokens`). `inherit` has no effect on cost records, which always belong to a project.",
         "parameters": [
           {
             "name": "groupBy",
@@ -19496,7 +20033,7 @@
               "type": "string"
             },
             "required": true,
-            "description": "Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId`. Duplicates collapse."
+            "description": "Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId | model | servedModel | projectId | orgId | rootRunId | flowId`. `model` is the model actually called; `servedModel` the exact version the vendor reported; `orgId` the org of the record's project. Duplicates collapse."
           },
           {
             "name": "from",
@@ -19516,7 +20053,7 @@
               "format": "date-time"
             },
             "required": false,
-            "description": "ISO 8601 timestamp; records with `occurredAt <= to`. Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window)."
+            "description": "ISO 8601 timestamp; records with `occurredAt < to` (exclusive). Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window)."
           },
           {
             "name": "category",
@@ -19565,6 +20102,44 @@
             "required": false,
             "description": "Filter records to this conversation id (exact match)."
           },
+          {
+            "name": "model",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "Filter model calls to this model, the one actually called (exact match)."
+          },
+          {
+            "name": "servedModel",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "description": "Filter model calls to the exact model version the vendor reported (exact match)."
+          },
+          {
+            "name": "rootRunId",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": false,
+            "description": "Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started."
+          },
+          {
+            "name": "includeDescendants",
+            "in": "query",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            },
+            "required": false,
+            "description": "With `runId`: the run's records and those of every run it started, at any depth. `true` or `false` (default)."
+          },
           {
             "name": "scopeKind",
             "in": "query",