---
title: "Get budget"
method: GET
path: "/api/v2/cost/budget/{budget_id}"
tags: ["Cloud Cost Management"]
---

# Get budget

`GET /api/v2/cost/budget/{budget_id}`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/cost/budget/{budget_id}`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

Get a budget by ID. Pass `actual=true` or `forecast=true` to include cost data in the response. Use `start` and `end` (millisecond epochs, both required) to set the cost window. When `forecast=true`, each entry also includes `ootb_forecast` (the ML forecast before overrides) and `custom_forecast` (`null` if no override is set, a number if one is).

## Path parameters

- `budget_id` string, required

## Query parameters

- `actual` boolean
- `forecast` boolean
- `start` integer
- `end` integer

## Response `200`

OK

- BudgetWithEntries: The definition of the `BudgetWithEntries` object.
  - `data` BudgetWithEntriesData: A budget and all its entries.
    - `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 `BudgetWithEntriesData` `id`.
    - `type` string: The type of the object, must be `budget`.

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `429`: Too many requests

---

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