---
title: "List budgets"
method: GET
path: "/api/v2/cost/budgets"
tags: ["Cloud Cost Management"]
---

# List budgets

`GET /api/v2/cost/budgets`

List budgets.

## Response `200`

OK

- BudgetArray — An array of budgets.
  - `data` Budget[], required — The `BudgetArray` `data`.
    - `attributes` BudgetAttributes — The attributes of a budget.
      - `costs` BudgetAttributesCosts — Aggregated cost data for the budget over the requested period.
        - `actual` number, double, nullable — The total actual cost. Present only when `actual=true` is requested.
        - `amount` number, double, nullable — The total budgeted amount over the requested period.
        - `forecast` number, double, nullable — The total forecast cost, with any custom forecast overrides applied. Present only when `forecast=true` is requested.
        - `ootb_forecast` number, double, nullable — The out-of-the-box ML forecast before custom overrides. Present only when `forecast=true` is requested.
      - `costs_period_end` integer — The end of the period used to compute cost data, in milliseconds since epoch.
      - `costs_period_start` integer — The start of the period used to compute cost data, in milliseconds since epoch.
      - `costs_unit` BudgetAttributesCostsUnit — The unit used for all cost values in the response.
        - `family` string — The unit family (for example, `currency`).
        - `id` string — The unique identifier for the unit.
        - `name` string — The full name of the unit.
        - `plural` string — The plural form of the unit name.
        - `scale_factor` number, double — The scale factor applied to raw cost values.
        - `short_name` string — The abbreviated unit name.
      - `created_at` integer — The timestamp when the budget was created.
      - `created_by` string — The id of the user that created the budget.
      - `end_month` integer — The month when the budget ends.
      - `entries` BudgetWithEntriesDataAttributesEntriesItems[] — The list of monthly budget entries.
        - `amount` number, double — The budgeted amount for this entry.
        - `costs` BudgetWithEntriesDataAttributesEntriesItemsCosts — Cost data for a single budget entry.
          - `actual` number, double, nullable — The actual cost for this entry. Present only when `actual=true` is requested.
          - `amount` number, double, nullable — The budgeted amount for this entry.
          - `custom_forecast` number, double, nullable — The custom forecast override for this entry. `null` when `forecast=true` is requested but no custom forecast has been set for this entry's month. A numeric value, including `0`, indicates an explicit custom forecast override. Omitted when `forecast=false` or the feature is not available for the organization.
          - `forecast` number, double, nullable — The final forecast for this entry, with any custom forecast override applied. Present only when `forecast=true` is requested.
          - `ootb_forecast` number, double, nullable — The out-of-the-box ML forecast for this entry, before custom overrides. Present only when `forecast=true` is requested.
        - `month` integer — The month this budget entry applies to, in YYYYMM format.
        - `tag_filters` BudgetWithEntriesDataAttributesEntriesItemsTagFiltersItems[] — The list of tag filters that scope this budget entry to specific resources.
          - `tag_key` string — The tag key to filter on.
          - `tag_value` string — The tag value to filter on.
      - `metrics_query` string — The cost query used to track against the budget.
      - `name` string — The name of the budget.
      - `org_id` integer — The id of the org the budget belongs to.
      - `start_month` integer — The month when the budget starts.
      - `total_amount` number, double — The sum of all budget entries' amounts.
      - `updated_at` integer — The timestamp when the budget was last updated.
      - `updated_by` string — The id of the user that created the budget.
    - `id` string — The id of the budget.
    - `type` string, required — The type of the object, must be `budget`.

## Other responses

- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)