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

# Budgets SDK Reference

> Manage spending budgets with the Node.js and Python SDKs: create, list, update, and delete budgets and reset consumption to control LLM costs.

## Budgets

Budget operations manage workspace spend controls and authenticate with a [Management Key](/ai-studio/organization/management-keys) that has the Budgets permission; a project-scoped API key cannot manage budgets. The SDK uses the Management Key as its API key.

### List Budgets

Returns budgets visible to the current workspace, ordered by most recently updated with the newest first. Supports filtering by scope kind, scope target id, period, and active state, plus an optional free-text query that matches scope target names and ids. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "scope_kind": List[Literal["BUDGET_SCOPE_KIND_UNSPECIFIED", "BUDGET_SCOPE_KIND_WORKSPACE", "BUDGET_SCOPE_KIND_PROJECT", "BUDGET_SCOPE_KIND_IDENTITY", "BUDGET_SCOPE_KIND_API_KEY", "BUDGET_SCOPE_KIND_PROVIDER", "BUDGET_SCOPE_KIND_MODEL"]],  # optional
        "scope_target_id": Optional[str],
        "is_active": Optional[bool],
        "period": List[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],  # optional
        "query": Optional[str],
        "sort_by": Optional[Literal["BUDGET_SORT_FIELD_UNSPECIFIED", "BUDGET_SORT_FIELD_EXPIRES_AT", "BUDGET_SORT_FIELD_CREATED_AT", "BUDGET_SORT_FIELD_UPDATED_AT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      scopeKind?: ("BUDGET_SCOPE_KIND_UNSPECIFIED" | "BUDGET_SCOPE_KIND_WORKSPACE" | "BUDGET_SCOPE_KIND_PROJECT" | "BUDGET_SCOPE_KIND_IDENTITY" | "BUDGET_SCOPE_KIND_API_KEY" | "BUDGET_SCOPE_KIND_PROVIDER" | "BUDGET_SCOPE_KIND_MODEL")[];
      scopeTargetId?: string;
      isActive?: boolean;
      period?: ("BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME")[];
      query?: string;
      sortBy?: "BUDGET_SORT_FIELD_UNSPECIFIED" | "BUDGET_SORT_FIELD_EXPIRES_AT" | "BUDGET_SORT_FIELD_CREATED_AT" | "BUDGET_SORT_FIELD_UPDATED_AT";
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": [{
            "budget_id": str,
            "scope": {  # optional
                "workspace": Dict[str, Any],  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": str,
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": str,  # optional
            "created_at": str,
            "updated_at": str,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
            "alerts": [{  # optional
                "id": Optional[str],
                "threshold_percent": int,
                "notifier_ids": List[str],
                "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
            }],
        }],
        "has_more": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        budgetId: string;
        scope?: {
          workspace?: Record<string, unknown>;
          project?: {
            projectId?: string;
          };
          identity?: {
            identityExternalId?: string;
          };
          apiKey?: {
            apiKeyId?: string;
          };
          provider?: {
            provider?: string;
          };
          model?: {
            modelId: string;
          };
        };
        match?: {
          cel?: string;
        };
        limits: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        createdAt: Date;
        updatedAt: Date;
        usage?: {
          amount?: number;
          tokens?: number;
          requests?: number;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;
          notifierIds: string[];
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
      }[];
      hasMore?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Budget

Creates a new budget in the workspace. Exactly one scope variant must be set (workspace / project / identity / api\_key / provider / model). At least one of `limits.amount`, `limits.token_limit`, or `rate_limit.requests_per_minute` MUST be provided. Uniqueness is enforced across (workspace\_id, scope\_kind, scope\_target\_id). Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.create()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.create({});

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "scope": {  # optional
            "workspace": Dict[str, Any],  # optional
            "project": {  # optional
                "project_id": Optional[str],
            },
            "identity": {  # optional
                "identity_external_id": Optional[str],
            },
            "api_key": {  # optional
                "api_key_id": Optional[str],
            },
            "provider": {  # optional
                "provider": Optional[str],
            },
            "model": {  # optional
                "model_id": str,  # required
            },
        },
        "match": {  # optional
            "cel": Optional[str],
        },
        "limits": {  # optional
            "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
            "amount": Optional[float],
            "token_limit": Optional[float],
        },
        "rate_limit": {  # optional
            "requests_per_minute": Optional[int],
        },
        "is_active": Optional[bool],
        "expires_at": str,  # optional
        "alerts": [{  # optional
            "id": Optional[str],
            "threshold_percent": int,  # required
            "notifier_ids": List[str],  # required
            "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      scope?: {
        workspace?: Record<string, unknown>;
        project?: {
          projectId?: string;
        };
        identity?: {
          identityExternalId?: string;
        };
        apiKey?: {
          apiKeyId?: string;
        };
        provider?: {
          provider?: string;
        };
        model?: {
          modelId: string;  // required
        };
      };
      match?: {
        cel?: string;
      };
      limits?: {
        period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
        amount?: number;
        tokenLimit?: number;
      };
      rateLimit?: {
        requestsPerMinute?: number;
      };
      isActive?: boolean;
      expiresAt?: Date;
      alerts?: {
        id?: string;
        thresholdPercent: number;  // required
        notifierIds: string[];  // required
        dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget": {
            "budget_id": str,
            "scope": {  # optional
                "workspace": Dict[str, Any],  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": str,
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": str,  # optional
            "created_at": str,
            "updated_at": str,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
            "alerts": [{  # optional
                "id": Optional[str],
                "threshold_percent": int,
                "notifier_ids": List[str],
                "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
            }],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budget: {
        budgetId: string;
        scope?: {
          workspace?: Record<string, unknown>;
          project?: {
            projectId?: string;
          };
          identity?: {
            identityExternalId?: string;
          };
          apiKey?: {
            apiKeyId?: string;
          };
          provider?: {
            provider?: string;
          };
          model?: {
            modelId: string;
          };
        };
        match?: {
          cel?: string;
        };
        limits: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        createdAt: Date;
        updatedAt: Date;
        usage?: {
          amount?: number;
          tokens?: number;
          requests?: number;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;
          notifierIds: string[];
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Budget

Retrieves the metadata for an existing budget by its unique identifier. Returns `NotFound` when the budget does not exist in the caller's workspace. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.get(budget_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.get({
      budgetId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budgetId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget": {
            "budget_id": str,
            "scope": {  # optional
                "workspace": Dict[str, Any],  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": str,
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": str,  # optional
            "created_at": str,
            "updated_at": str,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
            "alerts": [{  # optional
                "id": Optional[str],
                "threshold_percent": int,
                "notifier_ids": List[str],
                "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
            }],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budget: {
        budgetId: string;
        scope?: {
          workspace?: Record<string, unknown>;
          project?: {
            projectId?: string;
          };
          identity?: {
            identityExternalId?: string;
          };
          apiKey?: {
            apiKeyId?: string;
          };
          provider?: {
            provider?: string;
          };
          model?: {
            modelId: string;
          };
        };
        match?: {
          cel?: string;
        };
        limits: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        createdAt: Date;
        updatedAt: Date;
        usage?: {
          amount?: number;
          tokens?: number;
          requests?: number;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;
          notifierIds: string[];
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Budget

Permanently deletes a budget. Its consumption counters are cleared immediately. The response body is empty on success. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.delete(budget_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.delete({
      budgetId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budgetId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Budget

Updates mutable fields of a budget: limits, rate limit, activation, and expiration. The scope is immutable: to change a budget's target, delete and recreate it. Omitted fields keep their current values. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.update(budget_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.update({
      budgetId: "<id>",
      updateBudgetRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget_id": str,  # required
        "limits": {  # optional
            "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
            "amount": Optional[float],
            "token_limit": Optional[float],
        },
        "rate_limit": {  # optional
            "requests_per_minute": Optional[int],
        },
        "is_active": Optional[bool],
        "expires_at": str,  # optional
        "clear_expires_at": Optional[bool],
        "match": {  # optional
            "cel": Optional[str],
        },
        "alerts": [{  # optional
            "id": Optional[str],
            "threshold_percent": int,  # required
            "notifier_ids": List[str],  # required
            "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
        }],
        "clear_alerts": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budgetId: string;  // required
      updateBudgetRequest: {  // required
        limits?: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        clearExpiresAt?: boolean;
        match?: {
          cel?: string;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;  // required
          notifierIds: string[];  // required
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
        clearAlerts?: boolean;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget": {
            "budget_id": str,
            "scope": {  # optional
                "workspace": Dict[str, Any],  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": str,
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": str,  # optional
            "created_at": str,
            "updated_at": str,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
            "alerts": [{  # optional
                "id": Optional[str],
                "threshold_percent": int,
                "notifier_ids": List[str],
                "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
            }],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budget: {
        budgetId: string;
        scope?: {
          workspace?: Record<string, unknown>;
          project?: {
            projectId?: string;
          };
          identity?: {
            identityExternalId?: string;
          };
          apiKey?: {
            apiKeyId?: string;
          };
          provider?: {
            provider?: string;
          };
          model?: {
            modelId: string;
          };
        };
        match?: {
          cel?: string;
        };
        limits: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        createdAt: Date;
        updatedAt: Date;
        usage?: {
          amount?: number;
          tokens?: number;
          requests?: number;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;
          notifierIds: string[];
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Reset Consumption

Clears the current-period cost, token, and request counters for the budget. The budget record itself is preserved. Requires a Management Key with the Budgets permission; project-scoped API keys cannot manage budgets.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.budgets.reset_consumption(budget_id="<id>", reset_budget_consumption_request={})

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.budgets.resetConsumption({
      budgetId: "<id>",
      resetBudgetConsumptionRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget_id": str,  # required
        "reset_budget_consumption_request": Dict[str, Any],  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budgetId: string;  // required
      resetBudgetConsumptionRequest: Record<string, unknown>;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "budget": {  # optional
            "budget_id": str,
            "scope": {  # optional
                "workspace": Dict[str, Any],  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": str,
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": str,  # optional
            "created_at": str,
            "updated_at": str,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
            "alerts": [{  # optional
                "id": Optional[str],
                "threshold_percent": int,
                "notifier_ids": List[str],
                "dimension": Optional[Literal["BUDGET_ALERT_DIMENSION_UNSPECIFIED", "BUDGET_ALERT_DIMENSION_COST", "BUDGET_ALERT_DIMENSION_TOKENS"]],
            }],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      budget?: {
        budgetId: string;
        scope?: {
          workspace?: Record<string, unknown>;
          project?: {
            projectId?: string;
          };
          identity?: {
            identityExternalId?: string;
          };
          apiKey?: {
            apiKeyId?: string;
          };
          provider?: {
            provider?: string;
          };
          model?: {
            modelId: string;
          };
        };
        match?: {
          cel?: string;
        };
        limits: {
          period?: "BUDGET_PERIOD_UNSPECIFIED" | "BUDGET_PERIOD_DAILY" | "BUDGET_PERIOD_WEEKLY" | "BUDGET_PERIOD_MONTHLY" | "BUDGET_PERIOD_YEARLY" | "BUDGET_PERIOD_ONE_TIME";
          amount?: number;
          tokenLimit?: number;
        };
        rateLimit?: {
          requestsPerMinute?: number;
        };
        isActive?: boolean;
        expiresAt?: Date;
        createdAt: Date;
        updatedAt: Date;
        usage?: {
          amount?: number;
          tokens?: number;
          requests?: number;
        };
        alerts?: {
          id?: string;
          thresholdPercent: number;
          notifierIds: string[];
          dimension?: "BUDGET_ALERT_DIMENSION_UNSPECIFIED" | "BUDGET_ALERT_DIMENSION_COST" | "BUDGET_ALERT_DIMENSION_TOKENS";
        }[];
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.