List budgets
list_budgetsList a project's budget IDs and names to verify if budgets are tracked and to obtain IDs for use with attachments or other budget-related operations.
Instructions
List a project's budgets — their ids and names, which is all API v3 exposes.
Use it to see whether a project tracks budgets at all and to get a budget id, which is
what list_attachments(container_type='budget', ...) consumes.
Returns the standard list envelope with rows of {id, subject}. The collection is
fetched in full, so has_more is false.
Pitfalls — read before answering a money question. API v3's budget representer carries
no amounts: planned costs, spent costs, labor/material breakdowns and the assigned
work packages are simply not there. Do not infer them and do not present a budget row as
financial data; point the user at the budget in the UI, or use
get_project_report_data / list_time_entries for the effort side. Budgets are also a
module: a 404 (not installed, or not enabled in this project) and a 403 (this account
lacks 'view budgets') both come back as a SUCCESSFUL call with an empty items and the
reason in notes. Neither means the project has no budgets, so check notes before
answering — only an empty list with no notes means there are none.
Cross-references: list_projects for the project id; list_time_entries for logged
effort; list_attachments(container_type='budget', container_id=...) for budget files.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Numeric project id or URL identifier, from list_projects. Budgets are always read per project; there is no instance-wide budget listing. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |