---
title: "List organization budget histories"
method: GET
path: "/v2/organizations/{organization_id}/budget_histories"
tags: ["budgets"]
---

# List organization budget histories

`GET /v2/organizations/{organization_id}/budget_histories`

## Request

- Base URL: `https://api.hubstaff.com`
- URL: `https://api.hubstaff.com/v2/organizations/{organization_id}/budget_histories`
- Auth: OAuth 2
  - Authorization code: `https://account.hubstaff.com/authorizations/new`
  - Token URL: `https://account.hubstaff.com/access_tokens` scopes: `hubstaff:read`, `hubstaff:write`
- TypeScript: <https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/docs/v2/organizations/:organization_id/budget_histories/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns budget configuration history (changes to budget settings over time) for the given organization.

The project_ids and client_ids filters are processed as a complete set.

- If project_ids 1,2,3 and client_ids 4,5,6 are provided then all budget histories for those
project and clients will be returned.
- If only project_ids 1,2,3 (no client_ids filter) are provided then only budget histories for
those projects will be returned (no client budgets at all).
- If only client_ids 1,2,3 (no project_ids filter) are provided then only budget histories for
those clients will be returned (no project budgets at all).

Further resource may be specified to restrict only returning budget histories for either projects
or clients.
The resource filter is combined with the project_ids/client_ids filters thus
- If only project_ids is provided and resource = 'client' then no records will be returned

The start_date filters only apply to the starting date of the start_date of the budget history records.
Thus to fetch only budget histories for this month for all projects specify this filter
- resource=project and start_date[start]=2026-11-01

## Path parameters

- `organization_id` integer, required

## Query parameters

- `page_start_id` integer
- `page_limit` integer
- `project_ids` integer[]
- `client_ids` integer[]
- `resource` 'project' | 'client'
- `start_date[start]` string, date
- `start_date[stop]` string, date
- `include` string[]

## Response `200`

A list of budget histories

- object
  - `budget_histories` BudgetHistory[]
    - `id` integer, required: the budget history ID
    - `project_id` integer: The project ID the budget is for
    - `client_id` integer: The client ID the budget is for
    - `budget` Budget, required
      - `type` string, required: The budget type
      - `rate` string: The budget rate type
      - `cost` number, float: The budget cost limit
      - `hours` number, float: The budget hours limit
      - `start_date` string, date: The budget start date
      - `alerts` object, required
        - `near_limit` integer, required: The budget near limit percentage
        - `notify_enabled` boolean, required: Whether budget notifications are enabled
        - `notify_all_members` boolean, required: Whether to notify all project members
        - `notify_group` string: The group to notify
      - `recurrence` string: The budget recurrence frequency
      - `recurrence_start` integer: Day of week (0-6, 0=Sunday) for weekly recurrence, or day of month (1-31) for monthly recurrence
      - `include_non_billable` boolean, required: Whether the budget includes non-billable time
      - `stop_timer_when_budget_reached` boolean, required: Whether to stop timers when budget is reached
      - `stop_at` integer: The budget percentage at which timers stop
    - `start_date` string, date: The start date of the budget
    - `stop_date` string, date: The stop date of the budget
    - `spent` number, float, required: The amount spent. Either cost or hours depending on the budget type
    - `created_at` string, date-time, required: When the record was created
    - `updated_at` string, date-time, required: When the record was last updated

## Other responses

- `400`: Invalid parameters
- `401`: Unauthorized
- `403`: API access is only for organizations on an active plan
- `404`: Could not find record
- `429`: Rate limit exceeded

## Changes

- **2026-11-06** `c6b90e4e4bdc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/changes/v2/organizations/:organization_id/budget_histories/get.md)

---

[API](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api.md) - [All operations](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/revisions/c6b90e4e4bdc?raw)