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
}