> ## Documentation Index
> Fetch the complete documentation index at: https://developers.getbreezyapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recorded job profitability

> Use saved job costs and the existing costing revenue and report-date basis.

Recorded job costs and profitability are available at `/job-financials`, with a matching detail read using the job ID. Each resource includes the complete saved cost entries, qualifying invoice facts, current costing state, work dimensions, and distinct assigned company members. Pages order by job ID ascending. All jobs with an available owned account remain readable, including untracked, unverified, or excluded jobs. Missing or disabled company costing and untracked jobs have `totals:null`; saved costs and invoice facts remain available. Enabled tracked jobs retain their calculations regardless of verification or type inclusion.

## Query details or a summary

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.getbreezyapp.com/v1/job-financials?report_from=2026-09-01&report_before=2026-10-01&limit=100" \
  -H "Authorization: Bearer $BREEZY_API_KEY"
curl "https://api.getbreezyapp.com/v1/reports/job-profitability?start_date=2026-09-01&end_date=2026-10-01&bucket=week&group_by=business_unit" \
  -H "Authorization: Bearer $BREEZY_API_KEY"
curl "https://api.getbreezyapp.com/v1/reports/technician-participation-profitability?start_date=2026-09-01&end_date=2026-10-01&bucket=month" \
  -H "Authorization: Bearer $BREEZY_API_KEY"
```

## Revenue and report date

Costing revenue follows the existing job-costing dashboard: recorded invoice subtotals before discounts and taxes, for linked OPEN, PAID and UNCOLLECTABLE invoices. This differs from public invoice activity, collections, and recognized revenue. The complete `invoices` facts explain that revenue basis. The whole job uses the company-local date of its earliest qualifying non-null invoice issue time, falling back to work completion and then job creation; `report_date_basis` names the chosen source. All its current revenue and costs appear on this date, even if a later invoice or cost was recorded in another month.

## Costs, gross profit, and margin

Each saved labor cost is its recorded minutes / 60 × hourly cost; other categories use recorded quantity × unit cost. Each entry rounds to integer cents before summing, with half-cent ties away from zero. Unknown category strings are preserved and contribute `other_cost_cents`. Gross profit is revenue minus total cost; `gross_margin` is a fraction rounded to four decimal places, null at zero revenue, with signed amounts retained. A 0.7692 margin means 76.92%. In the examples, invoices 1001 and 1002 supply \$1,300 recorded subtotal on August 20; \$300 saved costs produce \$1,000 gross profit. This is distinct from the invoices' \$1,290 combined after-discount-and-tax total and their separate invoice-activity months.

Costs are saved business records. Reading this API does not populate missing costs from timesheets, synchronize invoice lines, or recalculate them using current wages or pricebook costs. A cost's `source` describes its recorded origin; it does not identify a worker or allocate revenue. Verification is the current recorded state, without an inferred verifier or approval timestamp. Current costs may differ from a later app visit that synchronizes them.

Profitability amounts must fit the documented signed integer range of −9,007,199,254,740,991 through 9,007,199,254,740,991 cents. A saved quantity or a sum of otherwise valid costs/jobs can exceed that range. Such a request returns the standard 500 `INTERNAL_ERROR` with no partial result; the API does not round away financial precision, clamp amounts or omit contributing records. Correct the source data, narrow the report scope where possible, or share `request_id` with support. Repeating an unchanged out-of-range query cannot recover the result.

## Report eligibility and grouping

Both profitability reports always require enabled company costing and TRACKED jobs. Defaults also require VERIFIED and a job type included in costing. Set `verified_only=false` or `include_excluded_job_types=true` to relax those respective rules; the latter includes jobs whose owned type is unavailable. A disabled report has empty data and `report.costing_enabled:false`. It does not claim the company earned zero profit. Dates and time buckets follow the [shared half-open local-date conventions](/conventions); empty buckets are omitted. Job profitability allows one `group_by` of business\_unit, job\_type or job\_class and keeps eligible unknown business groups. Both reports support account, business unit, job type/class and assigned-member filters. Overall margin must be calculated from summed revenue and profit, not averaged row margins.

For overlapping member totals, read [Technician performance](/technician-performance).

## Refresh the detail records

To build a local profitability store, page `/job-financials`, upsert by job ID, and replace each refreshed job's embedded invoices, costs and participants. Join `/jobs`, `/accounts`, `/team-members` and business catalogs for further segmentation. Collection filters include IDs, location, work dimensions, member, tracking/verification state, job-creation timestamp bounds and inclusive/exclusive local `report_from`/`report_before`. There is no financial `updated_since`: dependent invoices, costs, assignments, type inclusion and company configuration can change without a reliable shared timestamp. Refresh known job IDs and recent report-date windows, then periodically reconcile broader scopes. Corrections can move a job between dates or remove saved costs/assignments. A missing result in a filtered window does not prove deletion. Summary cursors page current results rather than freezing a snapshot.