list-budgets-tool

List budgets filtered by project, customer, budget group, status, billable/open flags or date range.

Returns paginated budgets with project, customer and budget group context. Each row also carries deadlines_count and times_count aggregates so the client can decide whether to dig deeper.

Inputs

Name	Type	Required	Description
`project_id`	integer	no	Limit to a single project.
`customer_id`	integer	no	Limit to budgets whose project belongs to this customer.
`budget_group_id`	integer	no	Limit to a single budget group.
`status`	string	no	One of `active`, `inactive`, `blocked`.
`is_open`	boolean	no	Filter open/closed budgets.
`is_billable`	boolean	no	Filter billable/non-billable budgets.
`search`	string	no	Substring match on the description (case-insensitive).
`start_date_from`	string (`Y-m-d`)	no	Inclusive lower bound on the start date.
`start_date_to`	string (`Y-m-d`)	no	Inclusive upper bound on the start date.
`end_date_from`	string (`Y-m-d`)	no	Inclusive lower bound on the end date.
`end_date_to`	string (`Y-m-d`)	no	Inclusive upper bound on the end date.
`limit`	integer	no	Page size, 1–100, default 25.
`offset`	integer	no	Number of rows to skip, default 0.

Permissions

budgets::read.

Example

{
  "project_id": 7,
  "is_open": true
}

Response

{
  "data": [
    {
      "id": 31,
      "description": "Design budget",
      "status": "active",
      "is_open": true,
      "is_billable": true,
      "budget": 2400,
      "spendable": 0,
      "start_date": "2026-01-15",
      "end_date": "2026-03-31",
      "deadlines_count": 1,
      "times_count": 6,
      "budget_group": null,
      "project": {
        "id": 7,
        "title": "ACME website",
        "customer": { "id": 3, "name": "ACME", "code": "ACM" }
      }
    }
  ],
  "pagination": { "total": 1, "limit": 25, "offset": 0, "has_more": false }
}

Errors

An invalid status value returns a validation error.
Missing budgets::read returns an authorization error.