Home / Python SDK / Python SDK reference

Budgets in SDK

Manage credits across orders and jobs using the SDK.

Overview

A budget helps you organize and track credit usage in your UP42 account by grouping orders and processing jobs by cost center. This provides better visibility into spending and can be linked to a project ID for internal tracking.

Assign a budget when creating orders or processing jobs to attribute credit consumption. You can also control spending with spend limit and validity period. Users won’t be able to create orders and jobs if the assigned budget’s spend limit would be exceeded or the budget is outside its validity period.

View repository

Class: Budget

A data class that represents a budget in the system.

Attributes

AttributeDescription
id

str

The budget ID.

name

str

The name of the budget.

status

BudgetStatus

The budget status.

created_by

str

The ID of the user who created the budget.

created_at

str

The timestamp when the budget was created.

updated_at

str

The timestamp when the budget was last updated.

description

Optional[str]

The description of the budget.

external_id

Optional[str]

The ID of the external project associated with the budget.

spend_limit

Optional[int]

The spend limit for this budget. Any consumption that would cause total credit consumption to exceed the limit fails. The total credit consumption aggregates all consumptions and refunds under this budget.

If the spend limit is set below the current budget usage, further consumption fails.

validity_period

Optional[ValidityPeriod]

The period during which the budget can be used for orders and processing jobs. The budget is valid from the start date through the end date, inclusive.

consumed_credits

Optional[int]

The number of credits consumed under this budget, after offsetting applicable refunds. Expressed as a negative value. Returned only if include_usage is enabled.

remaining_credits

Optional[int]

The number of credits remaining to spend under this budget. Can be negative if the credits consumed exceed the spend limit. If the budget doesn’t have a spend limit, the value is None. Returned only if include_usage is enabled.

usage_percentage

Optional[float]

The percentage of the spend limit consumed, rounded up to two decimals. Can be greater than 100% if the spend limit is set below current budget usage. If the budget doesn’t have a spend limit, the value is None. Returned only if include_usage is enabled.
Python
# Select a budget
budget_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"


# Fetch budget info
budget = up42.Budget.get(budget_id=budget_id, include_usage=True)


# Define output
print(f"Budget details for ID: {budget.id}")
print(f"Name:                  {budget.name}")
print(f"Status:                {budget.status}")
print(f"Description:           {budget.description}")
print(f"External ID:           {budget.external_id}")
print(f"Spend limit:           {budget.spend_limit}")
print(f"Consumed credits:      {budget.consumed_credits}")
print(f"Remaining credits:     {budget.remaining_credits}")
print(f"Usage percentage:      {budget.usage_percentage}")
if budget.validity_period:
    print(f"Valid from:            {budget.validity_period.start_date}")
    print(f"Valid until:           {budget.validity_period.end_date}")

Methods

all

Retrieves all budgets, with optional filtering. Returns Iterator[Budget]. Use itertools.islice to offset and limit the results.

ParameterDescription
status

Optional[List[BudgetStatus]]

Budget statuses. Use to search for budgets with any of the provided statuses.

sort_by

Optional[utils.SortingField]

The results sorting method that arranges elements in ascending or descending order based on a chosen field. To view the list of possible values, see BudgetSorting.

include_usage

Optional[bool]

Whether to include budget usage information in the response: consumed credits, remaining credits, and the percentage of the spend limit consumed.
Python
from itertools import islice


# Search for budgets
budgets = up42.Budget.all(
    status=["ACTIVE"],
    sort_by=up42.BudgetSorting.updated_at.desc,
    include_usage=True,
)


# Define output
for budget in islice(budgets, 0, 5): # Print first 5 results
    print(f"- Budget ID:   {budget.id}")
    print(f"  Name:        {budget.name}")
    print(f"  Status:      {budget.status}")
    print(f"  Updated at:  {budget.updated_at}")
    print(f"  Usage:       {budget.usage_percentage}%\n")

get

Retrieves a specific budget by its ID. Returns Budget.

ParameterDescription
budget_id

str

The budget ID.

include_usage

Optional[bool]

Whether to include budget usage information in the response: consumed credits, remaining credits, and the percentage of the spend limit consumed.
Python
# Select a budget
budget_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"


# Fetch budget info
budget = up42.Budget.get(budget_id=budget_id, include_usage=True)


# Define output
print(f"Budget details for ID: {budget.id}")
print(f"Name:                  {budget.name}")
print(f"Status:                {budget.status}")
print(f"Spend limit:           {budget.spend_limit}")
print(f"Consumed credits:      {budget.consumed_credits}")
print(f"Remaining credits:     {budget.remaining_credits}")
print(f"Usage percentage:      {budget.usage_percentage}")

get_usage

Retrieves the credit usage for a budget. Credit consumption is recorded when orders or processing jobs reach a specific status or substatus. Returns BudgetUsage.

Python
# Select a budget
budget_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"


# Fetch credit usage
budget = up42.Budget.get(budget_id=budget_id)
usage = budget.get_usage()


# Define output
print(f"Consumed credits:  {usage.consumed_credits}")

Class: ValidityPeriod

A data class that represents the period during which a budget can be used for orders and processing jobs. The budget is valid from the start date through the end date, inclusive.

Attributes

AttributeDescription
start_date

str

The start date of the budget’s validity period, in UTC. Before this date, the budget can’t be used.

end_date

str

The end date of the budget’s validity period, in UTC. After this date, the budget can’t be used. If the start date is set, the end date must be on or after it.
Python
# Select a budget
budget_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"


# Fetch budget info
budget = up42.Budget.get(budget_id=budget_id)


# Define output
if budget.validity_period:
    print(f"Valid from:  {budget.validity_period.start_date}")
    print(f"Valid until: {budget.validity_period.end_date}")

Class: BudgetUsage

A data class that represents the credit usage of a budget.

Attributes

AttributeDescription
budget_id

str

The budget ID.

consumed_credits

int

The number of credits consumed by all transactions associated with this budget.
Python
# Select a budget
budget_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"


# Fetch credit usage
budget = up42.Budget.get(budget_id=budget_id)
usage = budget.get_usage()


# Define output
print(f"Consumed credits:  {usage.consumed_credits}")

Class: BudgetSettings

A data class that represents the budget enforcement settings for an account.

Attributes

AttributeDescription
enforcement_enabled

bool

Indicates whether budget enforcement is enabled for the account. When enabled, a valid budget ID is required for orders and processing jobs.

budget_setting_id

Optional[str]

The budget setting ID.
Python
# Fetch budget settings
settings = up42.BudgetSettings.get()


# Define output
print(f"Enforcement enabled: {settings.enforcement_enabled}")
print(f"Budget setting ID:   {settings.budget_setting_id}")

Methods

get

Retrieves the budget enforcement settings for the account. Returns BudgetSettings.

Python
# Fetch budget settings
settings = up42.BudgetSettings.get()


# Define output
print(f"Enforcement enabled: {settings.enforcement_enabled}")

Class: BudgetSorting

A class that provides sorting options for budgets.

Attributes

AttributeDescription
updated_at

utils.SortingField

Sorts by update date. The default order is ascending.
Python
from itertools import islice


# Sort by update date, from the most recent to the earliest
budgets_sorted = up42.Budget.all(sort_by=up42.BudgetSorting.updated_at.desc)


# Define output
for budget in islice(budgets_sorted, 0, 5): # Print first 5 results
    print(f"- Budget ID:   {budget.id}")
    print(f"  Name:        {budget.name}")
    print(f"  Updated at:  {budget.updated_at}\n")

Learn more

API docs | Budgets Console docs | Budget management