Skip to content

README.md

Latest commit

 

History

History
275 lines (182 loc) · 34.6 KB

README.md

File metadata and controls

275 lines (182 loc) · 34.6 KB
Raw

Budgets

Overview

Available Operations

list

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.

Example Usage

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)

Parameters

Parameter Type Required Description
limit Optional[int] ➖ Page size, 1–200. Unset uses the server default (25).
starting_after Optional[str] ➖ Cursor for forward pagination. Set to the budget_id of the last
item from the previous page.
ending_before Optional[str] ➖ Cursor for backward pagination. Set to the budget_id of the
first item from the previous page.
scope_kind List[models.BudgetScopeKind] ➖ Optional filter: only return budgets whose scope kind matches one
of the listed values. Empty means no scope-kind filter.
scope_target_id Optional[str] ➖ Optional filter: only return budgets whose scope target id matches.
is_active Optional[bool] ➖ Optional filter: only return budgets with this active state.
period List[models.BudgetPeriod] ➖ Optional filter: only return budgets whose limits.period matches
one of the listed values. Empty means no period filter.
query Optional[str] ➖ Optional free-text query matched against a budget's scope target
name and id.
sort_by Optional[models.BudgetSortField] ➖ Field used to order the list. Unset orders by most-recently-updated.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListBudgetsResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

create

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.

Example Usage

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)

Parameters

Parameter Type Required Description
scope Optional[models.BudgetScope] ➖ Structured scope. Mutually exclusive with match: provide a scope
for the six canonical kinds (the server derives the matching CEL),
or provide match for a dynamic budget. Exactly one of the two
must be set; the handler enforces that invariant.
match Optional[models.BudgetMatch] ➖ Raw CEL matching expression for dynamic budgets (e.g.
metadata.team == "ml" && provider == "openai"). Validated via
CEL parse at write time. Mutually exclusive with scope.
limits Optional[models.BudgetLimits] ➖ At least one of amount / token_limit / rate_limit.requests_per_minute
must be provided on the budget; the handler enforces that invariant.
rate_limit Optional[models.RateLimit] ➖ Optional rate limit.
is_active Optional[bool] ➖ Whether the budget should be active immediately. Defaults to true
when omitted (handler enforces).
expires_at date ➖ Optional expiration. When set in combination with is_active=true,
the value MUST be in the future; the handler rejects past values.
alerts List[models.BudgetAlert] ➖ Optional threshold notifications. Ids are assigned by the server, so
alerts[].id must be omitted here; supplying one is rejected.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.CreateBudgetResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

get

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.

Example Usage

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)

Parameters

Parameter Type Required Description
budget_id str ✔️ Budget id to retrieve.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetBudgetResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete

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.

Example Usage

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)

Parameters

Parameter Type Required Description
budget_id str ✔️ Budget id to delete.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DeleteBudgetResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

update

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.

Example Usage

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)

Parameters

Parameter Type Required Description
budget_id str ✔️ Budget id to update.
limits Optional[models.BudgetLimits] ➖ New limits. Omit to keep current.
rate_limit Optional[models.RateLimit] ➖ New rate limit. Omit to keep current.
is_active Optional[bool] ➖ New active state. Omit to keep current.
expires_at date ➖ New expiration. Omit to keep current. Set clear_expires_at = true
to remove an existing expiration.
clear_expires_at Optional[bool] ➖ Force-clear the expiration. Mutually exclusive with expires_at.
match Optional[models.BudgetMatch] ➖ New matching expression. Only valid for dynamic budgets (no
structured scope) — the scope of a scoped budget is immutable, so
its derived expression is too. Validated via CEL parse.
alerts List[models.BudgetAlert] ➖ Replaces the alert list wholesale. Omit to keep the current alerts.
An entry with a known id is edited in place; one with no id is minted.
clear_alerts Optional[bool] ➖ Force-clear every alert. Mutually exclusive with a non-empty alerts.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.UpdateBudgetResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

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.

Example Usage

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)

Parameters

Parameter Type Required Description
budget_id str ✔️ Budget id whose current-period counters should be cleared.
reset_budget_consumption_request models.ResetBudgetConsumptionRequest ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ResetBudgetConsumptionResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*