Budgets

Get a single budget.

GET

https://firefly.example.com/api/v1/budgets/{id}

Get a single budget. If the start date and end date are submitted as well, the "spent" array will be updated accordingly.

curl -X GET 'https://firefly.example.com/api/v1/budgets/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://firefly.example.com/api/v1/budgets/123', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://firefly.example.com/api/v1/budgets/123',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "data": {
    "type": "budgets",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "active": false,
      "name": "Bills",
      "order": 5,
      "notes": "Some notes",
      "auto_budget_type": "reset",
      "auto_budget_period": "monthly",
      "object_group_id": "5",
      "object_group_order": 5,
      "object_group_title": "Example Group",
      "object_has_currency_setting": true,
      "currency_id": "5",
      "currency_name": "Euro",
      "currency_code": "EUR",
      "currency_symbol": "$",
      "currency_decimal_places": 2,
      "primary_currency_id": "5",
      "primary_currency_name": "Euro",
      "primary_currency_code": "EUR",
      "primary_currency_symbol": "$",
      "primary_currency_decimal_places": 2,
      "auto_budget_amount": "-1012.12",
      "pc_auto_budget_amount": "-1012.12",
      "spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ],
      "pc_spent": [
        {
          "currency_id": "5",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "sum": "123.45"
        }
      ]
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Parameters

idstringrequiredpath

The ID of the requested budget.

startstring<date>query

A date formatted YYYY-MM-DD, to get info on how much the user has spent.

endstring<date>query

A date formatted YYYY-MM-DD, to get info on how much the user has spent.

Response

200OKBudgetSingle

The requested budget

Response fields application/vnd.api+json

dataBudgetReadrequired

Show child attributes

typestringrequired

Immutable value

Example

budgets

idstringrequired

Example

attributesBudgetPropertiesrequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

activeboolean

Example

false

namestringrequired

Example

Bills

orderinteger<int32>read only

Example

notesstring | null

Example

Some notes

auto_budget_typeAutoBudgetType | nullresetrollovernonenull

The type of auto-budget that Firefly III must create.

Example

reset

auto_budget_periodAutoBudgetPeriod | nulldailyweeklymonthlyquarterlyhalf-yearyearlynull

Period for the auto budget

Example

monthly

object_group_idstring | null

The group ID of the group this object is part of. NULL if no group.

Example

object_group_orderinteger<int32> | nullread only

The order of the group. At least 1, for the highest sorting.

Example

object_group_titlestring | null

The name of the group. NULL if no group.

Example

Example Group

object_has_currency_settingbooleanread only

Indicates whether the object has a currency setting. If false, the object uses the administration's primary currency.

Example

true

currency_idstring

The currency ID of the currency associated with this object.

Example

currency_namestring

The currency name of the currency associated with this object.

Example

Euro

currency_codestring

The currency code of the currency associated with this object.

Example

EUR

currency_symbolstringread only

Example

currency_decimal_placesinteger<int32>read only

Example

primary_currency_idstringread only

The currency ID of the administration's primary currency.

Example

primary_currency_namestringread only

The currency name of the administration's primary currency.

Example

Euro

primary_currency_codestringread only

The currency code of the administration's primary currency.

Example

EUR

primary_currency_symbolstringread only

The currency symbol of the administration's primary currency.

Example

primary_currency_decimal_placesinteger<int32>read only

The currency decimal places of the administration's primary currency.

Example

auto_budget_amountstring<amount> | null

The amount for the auto-budget, if set.

Example

-1012.12

pc_auto_budget_amountstring<amount> | null

The amount for the auto-budget, if set in the primary currency of the administration.

Example

-1012.12

spentArray<ArrayEntryWithCurrencyAndSum>read only

Information on how much was spent in this budget. Is only filled in when the start and end date are submitted.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

pc_spentArray<ArrayEntryWithCurrencyAndSum>read only

Information on how much was spent in this budget. Is only filled in when the start and end date are submitted. It is converted to the primary currency of the administration.

Show child attributes

currency_idstring

Example

currency_codestring

Example

USD

currency_symbolstring

Example

currency_decimal_placesinteger<int32>

Number of decimals supported by the currency

Example

sumstring<amount>

The amount earned, spent or transferred.

Example

123.45

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.