Skip to content

Bills

list_bills

Retrieve the list of bills currently in the system.

Route: /api/v0/bills /api/v0/bills?period=previous

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?period=previous

Output:

{
 "status": "ok",
 "message": "",
 "count": 1,
 "bills": [
  {
   "bill_id": "1",
   "bill_name": "Router bills",
   "bill_type": "cdr",
   "bill_cdr": "10000000",
   "bill_day": "1",
   "bill_quota": "0",
   "rate_95th_in": "0",
   "rate_95th_out": "0",
   "rate_95th": "0",
   "dir_95th": "in",
   "total_data": "0",
   "total_data_in": "0",
   "total_data_out": "0",
   "rate_average_in": "0",
   "rate_average_out": "0",
   "rate_average": "0",
   "bill_last_calc": "2015-07-02 17:01:26",
   "bill_custid": "Router",
   "bill_ref": "Router",
   "bill_notes": "Bill me",
   "bill_autoadded": "0",
   "ports_total": "0",
   "allowed": "10Mbps",
   "used": "0bps",
   "percent": 0,
   "overuse": "-",
   "ports": [
       {
           "device_id": "168",
           "port_id": "35146",
           "ifName": "eth0"
       }
   ]
  }
 ]
}

get_bill

Retrieve a specific bill

Route: /api/v0/bills/:id /api/v0/bills/:id?period=previous /api/v0/bills?ref=:ref /api/v0/bills?ref=:ref&period=previous /api/v0/bills?custid=:custid /api/v0/bills?custid=:custid&period=previous

  • id is the specific bill id
  • ref is the billing reference
  • custid is the customer reference
  • period=previous indicates you would like the data for the last complete period rather than the current period

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?ref=:customerref
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?custid=:custid

Output:

{
 "status": "ok",
 "message": "",
 "count": 1,
 "bills": [
  {
   "bill_id": "1",
   "bill_name": "Router bills",
   "bill_type": "cdr",
   "bill_cdr": "10000000",
   "bill_day": "1",
   "bill_quota": "0",
   "rate_95th_in": "0",
   "rate_95th_out": "0",
   "rate_95th": "0",
   "dir_95th": "in",
   "total_data": "0",
   "total_data_in": "0",
   "total_data_out": "0",
   "rate_average_in": "0",
   "rate_average_out": "0",
   "rate_average": "0",
   "bill_last_calc": "2015-07-02 17:01:26",
   "bill_custid": "Router",
   "bill_ref": "Router",
   "bill_notes": "Bill me",
   "bill_autoadded": "0",
   "ports_total": "0",
   "allowed": "10Mbps",
   "used": "0bps",
   "percent": 0,
   "overuse": "-",
   "ports": [
       {
           "device_id": "168",
           "port_id": "35146",
           "ifName": "eth0"
       }
   ]
  }
 ]
}

get_bill_graph

Retrieve a graph image associated with a bill.

NB: The graphs returned from this will always be png as they do not come from rrdtool, even if you have SVG set.

Route: `/api/v0/bills/:id/graphs/:graph_type

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits?from=1517443200
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits?from=1517443200&to=1517788800
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/monthly

Output:

Graph Image

get_bill_graphdata

Retrieve the data used to draw a graph so it can be rendered in an external system

Route: /api/v0/bills/:id/graphdata/:graph_type

Input:

The reducefactor parameter is used to reduce the number of data points. Billing data has 5 minute granularity, so requesting a graph for a long time period will result in many data points. If not supplied, it will be automatically calculated. A reducefactor of 1 means return all items, 2 means half of the items etc.

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200&to=1517788800
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200&to=1517788800&reducefactor=5

Output:

{ "status": "ok", "graph_data": { "from": "1517443200", "to": 1518196161, "last": "1518195901", "in_data": [ 103190525.20999999, 104949255.81 ], "out_data": [ 1102059.1299999999, 1079216.46 ], "tot_data": [ 104292584.33999999, 106028472.27 ], "ticks": [ "1517750401", "1517756101" ], "rate_95th": "251880417", "rate_average": "146575554", "bill_type": "cdr", "max_in": 9888289942, "max_out": 75848756, "ave_in": 18029660.242105871, "ave_out": 196447.38060137472, "last_in": 3790227.9500000002, "last_out": 122731.63333333333 } }

get_bill_history

Retrieve the history of specific bill

Route: /api/v0/bills/:id/history

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history

Output:

{
 "status": "ok",
 "bill_history": [
    {
        "bill_hist_id": "1",
        "bill_id": "1",
        "updated": "2018-02-06 17:01:01",
        "bill_datefrom": "2018-02-01 00:00:00",
        "bill_dateto": "2018-02-28 23:59:59",
        "bill_type": "CDR",
        "bill_allowed": "100000000",
        "bill_used": "229963765",
        "bill_overuse": "129963765",
        "bill_percent": "229.96",
        "rate_95th_in": "229963765",
        "rate_95th_out": "1891344",
        "rate_95th": "229963765",
        "dir_95th": "in",
        "rate_average": "136527101",
        "rate_average_in": "135123359",
        "rate_average_out": "1403743",
        "traf_in": "3235123452544",
        "traf_out": "33608406566",
        "traf_total": "3268731859110",
        "bill_peak_out": "2782349290",
        "bill_peak_in": "10161119",
        "pdf": null
    }
 ],
 "count": 1,
}

get_bill_history_graph

Retrieve a graph of a previous period of a bill

NB: The graphs returned from this will always be png as they do not come from rrdtool, even if you have SVG set.

Route: /api/v0/bills/:id/history/:bill_hist_id/graphs/:graph_type

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/hour
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/day

Output:

(image)

get_bill_history_graphdata

Retrieve the data for a graph of a previous period of a bill, to be rendered in an external system

Route: /api/v0/bills/:id/history/:bill_hist_id/graphdata/:graph_type

Input:

Example:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/bits
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/hour
curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/day

Output:

delete_bill

Delete a specific bill and all dependent data

Route: /api/v0/bills/:id

  • id is the specific bill id

Input:

Example:

curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1

Output:

{
    "status": "ok",
    "message": "Bill has been removed"
}

create_edit_bill

Creates a new bill or updates an existing one

Route: /api/v0/bills

Method: POST

  • If you send an existing bill_id the call replaces all values it receives. For example if you send 2 ports it will delete the existing ports and add the the 2 new ports. So to add ports you have to get the current ports first and add them to your update call.

Input:

Example (create):

curl -X POST -d '{"ports":[ 1021 ],"bill_name":"NEWBILL","bill_day":"1","bill_type":"quota","bill_quota":"2000000000000","bill_custid":"1337","bill_ref":"reference1","bill_notes":"mynote"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills

Example (set):

curl -X POST -d '{"bill_id":"32","ports":[ 1021 ],"bill_name":"NEWNAME","bill_quota":"1000000000000"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills

Output:

{
    "status": "ok",
    "bill_id": 32
}