Working with results | CostCrunch Developer Docs

Methods are grouped like the CLI: cc.<group>.<action>(...), with the same parameters as keyword arguments. The Reference lists them all, and help(cc.documents.list) works too.

What comes back

Plain Python dicts and lists, ready for JSON or pandas.

Lists that can be paged return {"items": [...], "total": ..., "limit": ..., "offset": ..., "has_more": ...}.
Shorter lists (suppliers, projects, monthly spend) return a list.
get methods return one dict, with related lists inside (a document's line_items, a project's suppliers).

IDs can also be passed positionally: cc.documents.get(document_id).

Paging through everything

def all_documents(cc, **filters):
    offset = 0
    while True:
        page = cc.documents.list(limit=200, offset=offset, **filters)
        yield from page["items"]
        if not page["has_more"]:
            return
        offset += len(page["items"])

october = list(all_documents(cc, type="invoice", since="2026-10-01"))

Examples

Overpaid lines on recent invoices:

for doc in cc.documents.list(type="invoice", since="2026-10-01")["items"]:
    for line in cc.documents.lines(doc["id"]):
        if line["price_check"] == "overpaying":
            print(doc["supplier"], doc["number"], line["description"], line["price_impact"])

Spend by supplier into a spreadsheet:

import pandas as pd

pd.DataFrame(cc.suppliers.list()).to_excel("suppliers.xlsx", index=False)

A material's price over time:

m = cc.materials.find("5/8 sheetrock")["items"][0]
history = cc.materials.history(m["id"], since="2026-01-01", limit=100)
for buy in history["items"]:
    print(buy["date"], buy["supplier"], buy["price_per_unit"], buy["unit"])