---
title: "List budgets"
method: GET
path: "/budgets/{companyId}"
tags: ["Budgets"]
---

# List budgets

`GET /budgets/{companyId}`

Returns the budgets of a company, one row per budget period, ordered by target date (most recent first). Results are paginated: use `limit` to control page size and pass the returned `nextPageToken` to fetch the next page; `nextPageToken` is `null` once the last page has been reached. `startDate` is inclusive and `endDate` is exclusive; either bound can be used on its own to leave the other end of the range unbounded.

## Path parameters

- `companyId` string, required

## Query parameters

- `startDate` string, date — Only return budget periods with a target date on or after this date (inclusive).
- `endDate` string, date — Only return budget periods with a target date before this date (exclusive).
- `status` 'pending' | 'filled' | 'overdue' | 'carried' | 'discarded'
- `limit` integer — Maximum number of budget rows to return per page. Defaults to 50, maximum 200.
- `nextPageToken` string — Token to fetch the next page of results, taken from the `nextPageToken` returned by the previous request with the same filters. Omit it to fetch the first page. An invalid or malformed token is rejected with `404`.

## Response `200`

Successful Response

- ListBudgetsResponseSchema
  - `data` BudgetSchema[], required — Page of budget period rows.
    - `id` string, required — Embat ID of the budget period row. A budget spanning several periods returns one row per period, each with its own `id`.
    - `companyId` string, nullable — Embat company ID. You can get them from "companies" endpoints.
    - `categoryId` string, nullable — Embat category ID the budget is assigned to.
    - `description` string, nullable — Free-text description of the budget.
    - `currency` string, nullable — ISO 4217 currency code of the budget.
    - `source` 'API' | 'TELLME' | 'MANUAL' | 'AGENT'
    - `amount` number, nullable — Effective budgeted amount (original amount plus carried amounts).
    - `pendingAmount` number, nullable — Remaining amount not yet consumed by linked transactions.
    - `state` 'active' | 'closed'
    - `dateRange` BudgetDateRangeSchema
      - `start` string, date-time, nullable — Start of the budget period (inclusive).
      - `end` string, date-time, nullable — End of the budget period (inclusive).
    - `targetDate` string, date-time, nullable — Reference date of the budget period. Rows are sorted by it.
    - `periodicity` 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'biYearly' | 'yearly' | 'custom'
    - `projection` BudgetProjectionSchema
      - `id` string, nullable — Embat ID of the projection.
      - `name` string, nullable — Display name of the projection.
  - `nextPageToken` string, nullable — Token to fetch the next page. `null` once the last page has been reached.

## Other responses

- `400` — Bad request. The request is well-formed but cannot be processed.
- `401` — Unauthorized. The bearer token is missing, invalid or expired.
- `403` — Forbidden. The token does not grant access to this resource.
- `404` — Company not found, or `nextPageToken` is not a valid pagination token.
- `422` — Validation Error

## Changes

- **2026-08-31** `725860b66af9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/embat/apis/embat-api/changes/budgets/:companyId/get.md)

---

[API](https://skmtc.dev/embat/apis/embat-api.md) · [All operations](https://skmtc.dev/embat/apis/embat-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/embat/embat-api/revisions/8dca7fa9abc3/schema)