---
updatedAt: 2025-05-19T20:30:38.000Z
agentTools:
  projectIndex: https://developers.pocketsmith.com/llms.txt
---

# List budget for user

Lists the user's budget, consisting of one or more budget analysis packages, one per category. Akin to the list on the Budget page in PocketSmith.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "PocketSmith",
    "description": "The PocketSmith API",
    "contact": {
      "name": "API Support",
      "email": "api@pocketsmith.com"
    },
    "version": "2.0"
  },
  "x-samples-languages": [
    "curl",
    "node",
    "javascript",
    "php",
    "python"
  ],
  "servers": [
    {
      "url": "https://api.pocketsmith.com/v2",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "developerKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Developer-Key",
        "description": "If you want to build a tool just for yourself, be it a desktop widget to display your balances or a tool to import transactions from a bank without a bank feed, you can use our developer keys feature. You can issue yourself a key which will give you persistent API access to just your account. You should rotate your keys regularly."
      }
    },
    "schemas": {
      "Category": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique identifier of the category.",
            "example": 1438154
          },
          "title": {
            "type": "string",
            "description": "The title of the category.",
            "example": "Beer"
          },
          "colour": {
            "type": "string",
            "description": "The colour for the category.",
            "format": "CSS-style hex triplet",
            "example": "#00ff00"
          },
          "children": {
            "type": "array",
            "description": "The category's child categories.",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "parent_id": {
            "type": "integer",
            "description": "The unique identifier of the parent category of this category, or null if this category has no parent (i.e. is a top-level category)",
            "example": 42
          },
          "is_transfer": {
            "type": "boolean",
            "description": "Whether this category has been marked as a transfer category.",
            "example": false
          },
          "is_bill": {
            "type": "boolean",
            "description": "Whether the category is a bill category. A bill category is when budgeted amounts are normally spent at once, instead of spread across a budgeting period. This category will be included in the bill reminder email when set to true.",
            "example": true
          },
          "roll_up": {
            "type": "boolean",
            "description": "Whether the category's budget is rolled up into its parent category, if a parent category is present.",
            "example": false
          },
          "refund_behaviour": {
            "type": "string",
            "nullable": true,
            "description": "How the category's refunds or deductions should be reported on.",
            "enum": [
              "debits_are_deductions",
              "credits_are_refunds",
              null
            ],
            "example": "credits_are_refunds"
          },
          "created_at": {
            "type": "string",
            "description": "When the category was created.",
            "format": "ISO 8601 timestamp",
            "example": "2015-08-16T02:17:02Z"
          },
          "updated_at": {
            "type": "string",
            "description": "When the category was last updated.",
            "format": "ISO 8601 timestamp",
            "example": "2015-08-16T02:17:02Z"
          }
        }
      },
      "BudgetAnalysis": {
        "type": "object",
        "properties": {
          "start_date": {
            "type": "string",
            "description": "The start date of the budget analysis.",
            "example": "2016-11-01"
          },
          "end_date": {
            "type": "string",
            "description": "The end date of the budget analysis.",
            "example": "2016-11-30"
          },
          "currency_code": {
            "type": "string",
            "description": "The currency of the budget analysis.",
            "example": "nzd"
          },
          "total_actual_amount": {
            "type": "number",
            "description": "The total actual (transactions) amount across all periods.",
            "example": -42.3
          },
          "average_actual_amount": {
            "type": "number",
            "description": "The average actual (transactions) amount across all periods.",
            "example": -42.3
          },
          "total_forecast_amount": {
            "type": "number",
            "description": "The total budgeted amount across all periods.",
            "example": -60
          },
          "average_forecast_amount": {
            "type": "number",
            "description": "The average budgeted amount across all periods.",
            "example": -60
          },
          "total_over_by": {
            "type": "number",
            "description": "The total amount the budget was exceeded across all periods.",
            "example": 0
          },
          "total_under_by": {
            "type": "number",
            "description": "The total amount the budget was under by across all periods.",
            "example": 17.7
          },
          "periods": {
            "type": "array",
            "description": "The period analyses that this budget analysis comprises.",
            "items": {
              "$ref": "#/components/schemas/Period"
            }
          }
        }
      },
      "Period": {
        "type": "object",
        "properties": {
          "start_date": {
            "type": "string",
            "description": "The start date of the period.",
            "example": "2016-11-01"
          },
          "end_date": {
            "type": "string",
            "description": "The end date of the period.",
            "example": "2016-11-30"
          },
          "currency_code": {
            "type": "string",
            "description": "The currency of the period.",
            "example": "nzd"
          },
          "actual_amount": {
            "type": "number",
            "description": "The sum of all actuals (transactions) in the period.",
            "example": -42.3
          },
          "forecast_amount": {
            "type": "number",
            "description": "The sum of all forecast sources (budget events) in the period, for comparison against the actual amount.",
            "example": -60
          },
          "refund_amount": {
            "type": "number",
            "description": "This attribute tracks the amount that has been refunded or deducted to the actual amount. When a category is set to \"always expense\", any credit transactions are treated as refunds and when set to \"always income\", any debit transactions are treated as deductions.",
            "example": 5.6
          },
          "current": {
            "type": "boolean",
            "description": "Whether this period is current, such that the current date (in the user's time zone) falls within the date range.",
            "example": true
          },
          "over_budget": {
            "type": "boolean",
            "description": "Whether the budget has been exceeded in the period.",
            "example": false
          },
          "under_budget": {
            "type": "boolean",
            "description": "Whether the budget has not been exceeded in the period.",
            "example": true
          },
          "over_by": {
            "type": "number",
            "description": "How much the budget has been exceeded by in the period.",
            "example": 0
          },
          "under_by": {
            "type": "number",
            "description": "How much there is left in the budget for the period.",
            "example": 17.7
          },
          "percentage_used": {
            "type": "number",
            "description": "The percentage of the budget that has been used in the period.",
            "example": 70.5
          }
        }
      },
      "BudgetAnalysisPackage": {
        "type": "object",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "is_transfer": {
            "type": "boolean",
            "description": "Whether the expense budget analysis looks like a transfer to the income budget analysis, based on a number of heuristics.",
            "example": false
          },
          "expense": {
            "$ref": "#/components/schemas/BudgetAnalysis"
          },
          "income": {
            "$ref": "#/components/schemas/BudgetAnalysis"
          }
        }
      }
    }
  },
  "paths": {
    "/users/{id}/budget": {
      "get": {
        "summary": "List budget for user",
        "description": "Lists the user's budget, consisting of one or more budget analysis packages, one per category. Akin to the list on the Budget page in PocketSmith.",
        "tags": [
          "Budgeting"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier of the account.",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 42
          },
          {
            "name": "roll_up",
            "in": "query",
            "description": "Whether parent categories should have their children rolled up into them. When used, the children will still appear in the collection on their own, but their actual and forecast figures will be rolled up to the root parent.",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "example": true
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BudgetAnalysisPackage"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "developerKey": []
    }
  ]
}
```