> ## Documentation Index > Fetch the complete documentation index at: https://docs.finta.io/llms.txt > Use this file to discover all available pages before exploring further. # Get budget status > Returns planned, spent, rollover, available and pace for each budget in one plan and month, plus totals and spending no budget covers. Envelope plans also return `readyToAssign`, `paymentEnvelopes` and `unrecognizedCardInflows`. Finta computes every number at request time and counts only the plan's accounts. When `includesAccountsOutsideConsent` is true, the totals include accounts this key was not granted, named in `accountsOutsideConsent`, and their transactions stay unavailable to it. `plan` is null if the user has no budgets yet. ## OpenAPI ````yaml /api/v2/openapi.json get /budgets/status openapi: 3.0.3 info: title: Finta API v2 version: 2.0.0 description: >- DB-backed Finta API for users with storage mode enabled. Requires an API key or an OAuth access token, and an active subscription or free trial. ## Rate limits Rate limits are enforced per user based on subscription plan, separately from MCP. The free trial gets Standard limits, or Pro limits if you're trialing Pro: | Plan | Per minute | Per day | | --- | --- | --- | | Standard | 20 requests | 500 requests | | Pro | 60 requests | 2,000 requests | When a limit is exceeded, the API returns HTTP 429 with `error.code` `RATE_LIMITED` and a human-readable `message`. A `Retry-After` response header is included with the number of seconds until the window resets. servers: - url: https://api.finta.io/v2 description: Production server security: - bearerAuth: [] tags: - name: Me description: Authenticated user - name: Health description: Service health - name: Bank Connections description: Bank connection resources - name: Accounts description: Account and balance history resources - name: Investments description: Securities, holdings, and investment transaction resources - name: Transactions description: Transaction resources - name: Categories description: Transaction category resources - name: Category Groups description: Category group resources - name: Rules description: Transaction rule resources - name: Budgets description: Budget plans, budgets, and budget status paths: /budgets/status: get: tags: - Budgets summary: Get budget status description: >- Returns planned, spent, rollover, available and pace for each budget in one plan and month, plus totals and spending no budget covers. Envelope plans also return `readyToAssign`, `paymentEnvelopes` and `unrecognizedCardInflows`. Finta computes every number at request time and counts only the plan's accounts. When `includesAccountsOutsideConsent` is true, the totals include accounts this key was not granted, named in `accountsOutsideConsent`, and their transactions stay unavailable to it. `plan` is null if the user has no budgets yet. operationId: getBudgetStatusV2 parameters: - name: plan in: query required: false schema: type: string minLength: 1 maxLength: 100 description: Plan name or id. Defaults to the default plan. - name: period in: query required: false schema: type: string default: current description: '`current` (in the user''s timezone) or a month as YYYY-MM' responses: '200': description: Budget status for the month content: application/json: schema: $ref: '#/components/schemas/BudgetStatusResponse' '400': description: Invalid period or query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: Storage mode required or subscription inactive content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- `NOT_FOUND`. The plan, budget, category or account does not exist, or budgets are not enabled for this account yet. A bad plan lists the user's plan names in `message`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimitedResponse' components: schemas: BudgetStatusResponse: type: object required: - planId - plan - period - currency - totals - readyToAssign - balancesAsOf - budgets - unbudgeted - paymentEnvelopes - unrecognizedCardInflows - meta - includesAccountsOutsideConsent - accountsOutsideConsent properties: planId: type: string format: uuid nullable: true plan: allOf: - $ref: '#/components/schemas/BudgetPlan' nullable: true period: $ref: '#/components/schemas/BudgetPeriod' currency: type: string nullable: true totals: type: object description: >- A category budget inside a budgeted group counts once, through the group. required: - planned - spent - rollover - available - unbudgetedSpent - uncategorizedSpent - totalSpent properties: planned: type: number spent: type: number rollover: type: number available: type: number unbudgetedSpent: type: number description: Spend in categories no budget covers uncategorizedSpent: type: number description: Spend on transactions with no category totalSpent: type: number readyToAssign: type: number nullable: true description: >- Depository balances minus `totals.available` minus every payment envelope's `available`, over the plan's accounts. Negative when over-assigned. Null unless this is an envelope plan's current month. balancesAsOf: type: string format: date-time nullable: true description: Time of the oldest balance behind `readyToAssign` budgets: type: array items: $ref: '#/components/schemas/BudgetStatusEntry' unbudgeted: type: array items: type: object required: - categoryId - name - categoryGroupId - spent properties: categoryId: type: string format: uuid name: type: string nullable: true categoryGroupId: type: string format: uuid nullable: true spent: type: number paymentEnvelopes: type: array description: One per credit card in an envelope plan's accounts. Otherwise empty. items: type: object required: - budgetId - accountId - name - assigned - rollover - movedIn - paid - available - owed properties: budgetId: type: string format: uuid nullable: true description: Null until the first assignment accountId: type: string format: uuid name: type: string assigned: type: number rollover: type: number description: Carried from earlier months movedIn: type: number description: Budgeted spend on this card this month, net of refunds paid: type: number available: type: number description: What's set aside for the payment owed: type: number description: >- The card's current balance, whichever month this is. Not subtracted from `readyToAssign`. unrecognizedCardInflows: type: object nullable: true description: >- This month's inflows on a card in an income category or with no category. Null for standard plans. required: - count - amount properties: count: type: integer amount: type: number meta: type: object required: - planCount - budgetCount - rolloverBudgetCount - maxRolloverPeriodsWalked - totalRolloverPeriodsWalked - rolloverWalkTruncated - queryCount properties: planCount: type: integer budgetCount: type: integer rolloverBudgetCount: type: integer maxRolloverPeriodsWalked: type: integer totalRolloverPeriodsWalked: type: integer rolloverWalkTruncated: type: boolean queryCount: type: integer includesAccountsOutsideConsent: type: boolean description: True when the totals include accounts this key was not granted accountsOutsideConsent: type: array items: type: object required: - id - name properties: id: type: string format: uuid name: type: string ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: STORAGE_MODE_REQUIRED message: type: string UnauthorizedResponse: type: object required: - error properties: error: type: string example: Missing or invalid Authorization header BudgetPlan: type: object required: - id - name - method - accountScope - isDefault properties: id: type: string format: uuid name: type: string method: type: string enum: - standard - envelope accountScope: type: string enum: - All - Selected isDefault: type: boolean BudgetPeriod: type: object required: - key - cadence - startDate - endDate properties: key: type: string example: 2026-11 cadence: type: string enum: - monthly startDate: type: string format: date endDate: type: string format: date BudgetStatusEntry: type: object required: - budgetId - targetType - categoryId - categoryGroupId - name - categoryIds - rolloverEnabled - planned - plannedSource - suggestedAmount - overrideSource - spent - rollover - available - pace - targetProgress - rolloverPeriodsWalked properties: budgetId: type: string format: uuid targetType: type: string enum: - category - category_group categoryId: type: string format: uuid nullable: true categoryGroupId: type: string format: uuid nullable: true name: type: string nullable: true categoryIds: type: array items: type: string format: uuid description: Categories whose spend counts toward this budget rolloverEnabled: type: boolean planned: type: number plannedSource: type: string enum: - template - override - unassigned description: >- `unassigned` is an envelope plan's month with nothing assigned, so `planned` is 0. suggestedAmount: type: number nullable: true description: 'Envelope plans: the template, as a quick-fill suggestion' overrideSource: type: string enum: - user_edited - snapshot nullable: true spent: type: number rollover: type: number available: type: number description: What's left. Negative when overspent. pace: type: object required: - periodElapsedRatio - spentRatio - status - projectedSpend properties: periodElapsedRatio: type: number spentRatio: type: number nullable: true status: type: string enum: - under - on_track - over - unknown projectedSpend: type: number nullable: true targetProgress: type: object nullable: true required: - targetAmount - targetDate - currentAmount - remainingAmount - progressRatio - isMet - periodsRemaining - requiredPerPeriod properties: targetAmount: type: number targetDate: type: string format: date nullable: true currentAmount: type: number remainingAmount: type: number progressRatio: type: number nullable: true isMet: type: boolean periodsRemaining: type: integer nullable: true requiredPerPeriod: type: number nullable: true rolloverPeriodsWalked: type: integer responses: RateLimitedResponse: description: Rate limit exceeded headers: Retry-After: description: Seconds until the rate-limit window resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Per-minute rate limit exceeded (standard plan) securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Finta API key from API settings, or an OAuth access token issued to an authorized app. Send either as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.