# createTokenBudget `POST /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/tokenbudgets` create a token budget ## Request ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `ProjectId` | string | Yes | Unique identifier of the project. | ### Request body create token budget request `application/json` - `apiVersion` (string) - `kind` (string) - `metadata` (object) - `name` (string) - `uid` (string) - `resourceVersion` (integer) - `createdAt` (string) - `updatedAt` (string) - `deletedAt` (string) - `labels` (object) - `annotations` (object) - `spec` (object) — Required. - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored. - `scope` (object) — Scope selects which conversation requests a TokenBudget applies to. Empty selectors match anything; set selectors are AND-combined. - `appId` (string) — AppID limits the budget to a single App ID within the project. - `component` (string) — Component limits the budget to a single conversation component name. - `model` (string) — Model limits the budget to a single model. - `limit` (integer (int64)) — Required. Limit is the token allowance per window (total prompt + completion tokens as reported by the provider). - `window` (string) — Required. Window is the period after which consumption resets. One of: `hour`, `day`, `month`. - `mode` (string) — Required. Mode controls enforcement: "enforce" rejects over-budget requests, "alert" only counts. One of: `enforce`, `alert`. - `epoch` (integer (int64)) — Read-only. Epoch counts the resets of this budget's usage. It is server-owned: a create starts it at zero, ordinary updates preserve it, and the reset endpoint advances it. The dataplane folds it into the budget's counter identity, so every reset starts a fresh counter and a fresh utilization reading, and the old ones age out on their own. - `status` (object) - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `instances` (object[]) — Instances includes the status for each instance of the resource. - `cluster` (string) — Cluster is the name of the cluster hosting this instance. - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1"). - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1"). - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `utilization` (object) — Utilization reports how much of a budget's allowance has been consumed in the window that is currently open. - `consumed` (integer (int64)) — Consumed is the tokens charged so far in the current window. - `remaining` (integer (int64)) — Remaining is the allowance left, floored at zero. A budget that has overshot reports zero rather than a negative number. - `limit` (integer (int64)) — Limit is the allowance in force when this was observed. It follows an edit to Spec.Limit within a reporting interval of the edit reaching the sidecar, which re-derives its reading under the new limit without waiting for traffic. A lasting difference means the edit has not reached the sidecar. - `exhausted` (boolean) — Exhausted is true when the budget had no allowance left at ObservedAt. For an enforce-mode budget this is why requests are being rejected. - `windowEndsAt` (string) — WindowEndsAt is when the counter resets and consumption returns to zero. Omitted when the counter backend does not report it. - `observedAt` (string) — ObservedAt is when the dataplane last observed this consumption, on a charge or on a checked request. A limit edit re-derives the rest of the reading without moving it. It does not advance while the reading is republished unchanged, so an old timestamp means the budget has had no traffic since, not that reporting stopped. - `accuracy` (string) — Accuracy is "exact" or "partial" — see AccuracyExact and AccuracyPartial. Do not alert on a "partial" number. Example: ```json { "apiVersion": "cra.diagrid.io/v1beta1", "kind": "TokenBudget", "metadata": { "name": "dev-assistant-daily" }, "spec": { "projectId": "my-project", "scope": { "appId": "dev-assistant" }, "limit": 1000000, "window": "day", "mode": "enforce" } } ``` `application/vnd.api+json` - `data` (object) - `apiVersion` (string) - `kind` (string) - `metadata` (object) - `name` (string) - `uid` (string) - `resourceVersion` (integer) - `createdAt` (string) - `updatedAt` (string) - `deletedAt` (string) - `labels` (object) - `annotations` (object) - `spec` (object) — Required. - `projectId` (string) — Required. Read-only. Immutable. ProjectID is server-derived from the request path; the client-supplied value is ignored. - `scope` (object) — Scope selects which conversation requests a TokenBudget applies to. Empty selectors match anything; set selectors are AND-combined. - `appId` (string) — AppID limits the budget to a single App ID within the project. - `component` (string) — Component limits the budget to a single conversation component name. - `model` (string) — Model limits the budget to a single model. - `limit` (integer (int64)) — Required. Limit is the token allowance per window (total prompt + completion tokens as reported by the provider). - `window` (string) — Required. Window is the period after which consumption resets. One of: `hour`, `day`, `month`. - `mode` (string) — Required. Mode controls enforcement: "enforce" rejects over-budget requests, "alert" only counts. One of: `enforce`, `alert`. - `epoch` (integer (int64)) — Read-only. Epoch counts the resets of this budget's usage. It is server-owned: a create starts it at zero, ordinary updates preserve it, and the reset endpoint advances it. The dataplane folds it into the budget's counter identity, so every reset starts a fresh counter and a fresh utilization reading, and the old ones age out on their own. - `status` (object) - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `instances` (object[]) — Instances includes the status for each instance of the resource. - `cluster` (string) — Cluster is the name of the cluster hosting this instance. - `region` (string) — Region is the region where the instance is located (e.g. "us-east-1"). - `placementId` (string) — PlacementID is the project placement this instance belongs to (e.g. "1"). - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `utilization` (object) — Utilization reports how much of a budget's allowance has been consumed in the window that is currently open. - `consumed` (integer (int64)) — Consumed is the tokens charged so far in the current window. - `remaining` (integer (int64)) — Remaining is the allowance left, floored at zero. A budget that has overshot reports zero rather than a negative number. - `limit` (integer (int64)) — Limit is the allowance in force when this was observed. It follows an edit to Spec.Limit within a reporting interval of the edit reaching the sidecar, which re-derives its reading under the new limit without waiting for traffic. A lasting difference means the edit has not reached the sidecar. - `exhausted` (boolean) — Exhausted is true when the budget had no allowance left at ObservedAt. For an enforce-mode budget this is why requests are being rejected. - `windowEndsAt` (string) — WindowEndsAt is when the counter resets and consumption returns to zero. Omitted when the counter backend does not report it. - `observedAt` (string) — ObservedAt is when the dataplane last observed this consumption, on a charge or on a checked request. A limit edit re-derives the rest of the reading without moving it. It does not advance while the reading is republished unchanged, so an old timestamp means the budget has had no traffic since, not that reporting stopped. - `accuracy` (string) — Accuracy is "exact" or "partial" — see AccuracyExact and AccuracyPartial. Do not alert on a "partial" number. ## Responses ### 202 — TokenBudget accepted for [asynchronous processing](https://jsonapi.org/recommendations/#asynchronous-processing). ### 404 — TokenBudget [not found](https://jsonapi.org/format/#crud-creating-responses-404). `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. ### 409 — TokenBudget name is in [conflict](https://jsonapi.org/format/#crud-creating-responses-409). `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. ### default — Unexpected error. `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.