Skip to content
COMMITLYCOMMITLYCOMMITLY Developers

List budgets of a scenario

GET
/scenarios/{scenario_id}/budgets/
curl --request GET \
  --url 'https://app.commitly.com/api/scenarios/12459/budgets/?budget_type=single&page_size=100' \
  --header 'Authorization: Bearer <token>'

Returns the budgets of the given scenario. The list contains only the scenario’s own budgets, not the forecast budgets it is based on.

Note the response shape: results is an object containing the total and the budgets array, not an array.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
scenario_id
required
integer

Scenario ID (id of a plan with type SCENARIO from GET /plans/).

Example
12459

Query Parameters

Section titled “Query Parameters”
category
Array<integer>

Category ID; includes its subcategories. Repeat the parameter for several categories.

min_date
string format: date

Earliest settlement_date.

max_date
string format: date

Latest settlement_date.

min_value
number

Minimum amount.

max_value
number

Maximum amount.

source
string

Substring match on external_source. Several comma-separated values are combined with OR.

budget_type
string
Allowed values: single recurring dynamic contract

Kind of budget.

recurrent
boolean

Boolean filter on recurring budgets.

open
boolean

Boolean filter on open budgets.

contracts
boolean

Boolean filter on contract budgets.

empty_tags
boolean

true: budgets without tags.

ids
string

Comma-separated internal budget IDs.

tags
string

Comma-separated tags.

search
string

Searches name, description and tags.

ordering
string

Sort order. Allowed fields: start_date, settlement_date, amount, end_date. Prefix a field with - for descending order.

page
integer
>= 1

Page number, starting at 1. When paging through results, read this value from the next link and send it to the documented base URL.

page_size
integer
default: 100 >= 1 <= 1000

Number of records per page. Default 100, maximum 1000; larger values are reduced to 1000.

Responses

Section titled “Responses”

200

Section titled “200”

Paginated list of budgets with total.

Media typeapplication/json
object
count
required

Total number of matching records.

integer
next
required

URL of the next page, or null on the last page. The host name may differ from the documented base URL; read page from it and call the documented base URL.

string | null format: uri
previous
required

URL of the previous page, or null on the first page.

string | null format: uri
sum

Sum of the amounts of all matching budgets.

number
results

Total and the budgets of the current page.

object
total

Total amount of all matching budgets.

number
budgets
Array<object>

Budget as returned by the API.

object
id

Internal budget ID; used in the /budgets/{id}/ paths.

integer
category

Short form of a category, embedded in transactions and budgets.

object
id
integer
name
string
description
string
inter_category

Category of the linked budget in the other company.

integer | null
inter_category_name

Name of inter_category.

string | null
depending_categories

Categories the budget depends on.

Array
base_categories

Stored dependency categories (set via depending_categories).

Array
recurring_budget

Summary of the recurrence settings; null if the budget is not recurring.

object
frequency
string
frequency_multiplier
integer
sequence_type
string
sequence_term_size
integer
d
number
r
number
settlement_date
string format: date
start_date
string | null format: date
end_date
string | null format: date
account

Bank account ID.

integer | null
tags
Array<string>
integration_tags
Array<string> | null
is_adjusted
boolean
inter_budget

The linked budget in the other company of an intercompany budget, or null.

name
string
description
string
amount

Negative for outflows, positive for inflows.

number
rate
number
base

FS forecast and scenario, S scenario, F forecast.

string
Allowed values: FS S F
time_lags
Array<integer>
frequency
string
Allowed values: daily weekly monthly quarterly yearly ""
frequency_multiplier
integer
sequence_type
string
Allowed values: AP GP HP ""
sequence_term_size
integer
d
number
r
number
is_indefinite
boolean
external_id

Your own ID for the budget.

string | null
external_source

Free-text name of the system that created the budget.

string | null
inter_company

Company ID for an intercompany budget.

integer | null
source

ID of the budget this one was copied from, or null. Not related to external_source.

integer | null
Examples
ExampleBudgetPage

Budget list

{
  "count": 1,
  "sum": 125,
  "next": null,
  "previous": null,
  "results": {
    "total": 125,
    "budgets": [
      {
        "id": 9001,
        "category": {
          "id": 1002,
          "name": "Revenue",
          "description": ""
        },
        "inter_category": null,
        "inter_category_name": null,
        "depending_categories": [],
        "recurring_budget": null,
        "settlement_date": "2023-01-15",
        "start_date": null,
        "end_date": null,
        "account": null,
        "tags": [],
        "integration_tags": null,
        "is_adjusted": false,
        "inter_budget": null,
        "name": "Consulting project",
        "description": "",
        "amount": 125,
        "rate": 0,
        "base": "FS",
        "time_lags": [],
        "frequency": "",
        "frequency_multiplier": 1,
        "sequence_type": "",
        "sequence_term_size": 1,
        "d": 0,
        "r": 1,
        "is_indefinite": false,
        "external_id": "123456",
        "external_source": "my-integration",
        "inter_company": null,
        "source": null
      }
    ]
  }
}

401

Section titled “401”

The access token is invalid or has expired. Request a new token. The message is localized (see Accept-Language).

Media typeapplication/json
object
detail
required

Error message.

string
code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string
Example
{
  "detail": "Invalid token."
}

Headers

Section titled “Headers”
WWW-Authenticate
string

Authentication scheme, Bearer.

Example
Bearer

403

Section titled “403”

No access token was sent, or the credentials are not allowed to call this endpoint. If the company’s COMMITLY edition does not include the requested function, the body additionally contains "code": "billing_plan_permission_denied".

Media typeapplication/json
object
detail
required

Error message.

string
code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string
Example
{
  "detail": "User must be authenticated to access this resource."
}

404

Section titled “404”

The resource does not exist or is not accessible with these credentials.

Media typeapplication/json
object
detail
required

Error message.

string
code

Present only if the company’s edition does not include the function; value billing_plan_permission_denied.

string
Examplegenerated
{
  "detail": "example",
  "code": "example"
}