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

# Get trend analysis for user

Get an income and/or expense budget analysis for the given date range and period across any number of categories and scenarios. Akin to the Trends 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."
      }
    },
    "responses": {
      "400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "403": {
        "description": "Not Allowed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "404": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "422": {
        "description": "Validation Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "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"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "A message describing the error that occurred.",
            "example": "A message describing the error that occurred."
          }
        }
      }
    }
  },
  "paths": {
    "/users/{id}/trend_analysis": {
      "get": {
        "summary": "Get trend analysis for user",
        "description": "Get an income and/or expense budget analysis for the given date range and period across any number of categories and scenarios. Akin to the Trends page in PocketSmith.",
        "tags": [
          "Budgeting"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier of the user.",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": 42
          },
          {
            "name": "period",
            "in": "query",
            "description": "The period to analyse in, one of `weeks`, `months` or `years`. Also supported is `event`, although event period analysis is only possible when the budget events gathered align, so in this case where all categories are analysed together, it's highly unlikely that event period analysis will be possible.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "weeks",
                "months",
                "years",
                "event"
              ]
            },
            "example": "weeks"
          },
          {
            "name": "interval",
            "in": "query",
            "description": "The period interval, e.g. if the interval is 2 and the period is weeks, the budget will be analysed fortnightly.",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "example": true
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "The date to start analysing the budget from. This will be bumped out to make full periods as necessary.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2016-11-01"
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "The date to stop analysing the budget from. This will be bumped out to make full periods as necessary.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2016-11-30"
          },
          {
            "name": "categories",
            "in": "query",
            "description": "A comma-separated list of category IDs to analyse.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "42,49"
          },
          {
            "name": "scenarios",
            "in": "query",
            "description": "A comma-separated list of scenario IDs to analyse. You're likely going to want to include all a user's scenarios here, unless you have reason to only analyse for a subset of scenarios. Regardless of what scenarios are analysed, all actuals (transactions) across all accounts will be included.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "11,29"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BudgetAnalysisPackage"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "422": {
            "$ref": "#/components/responses/422"
          }
        }
      }
    }
  },
  "security": [
    {
      "developerKey": []
    }
  ]
}
```