> ## 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.

# Page jobs with recorded costs and costing revenue

> One resource per owned job, identified by job ID and ordered by ID ascending. Complete saved costs, qualifying invoice facts and distinct assigned company members. Disabled or untracked costing has null totals while saved facts remain readable. Date filters refer to job creation or the company-local financial report date. No financial updated_since or snapshot.



## OpenAPI

````yaml /openapi.json get /job-financials
openapi: 3.0.3
info:
  title: Breezy Public Reporting API
  version: 1.0.0
  description: >-
    Read customers, team members, jobs, visits, assignments, installed
    equipment, captured form responses, time entries, configured-period
    timesheets, business reference catalogs, job leads, estimates, invoices,
    payments, refunds, recorded job financials, saved sold/earned credits, and
    financial summaries for your company. Existing API keys grant company-wide
    read access. Amounts are integer USD cents. Reads return current corrected
    records, with cursor pagination for collecting results.


    Read the [Breezy FSM guides](https://developers.getbreezyapp.com) for
    authentication, pagination, refresh limits, and business measures. All reads
    use latest corrected company records; cursors do not create a snapshot or a
    complete change feed.
servers:
  - url: https://api.getbreezyapp.com/v1
    description: Breezy FSM production API
security:
  - apiKey: []
tags:
  - name: Company
  - name: Invoices
  - name: Payments
  - name: Refunds
  - name: Reports
  - name: TeamMembers
  - name: Accounts
  - name: Contacts
  - name: Locations
  - name: Jobs
  - name: JobAppointments
  - name: JobAssignments
  - name: BusinessUnits
  - name: JobTypes
  - name: JobClasses
  - name: JobLifecycles
  - name: LeadSources
  - name: Tags
  - name: Estimates
  - name: JobLeads
  - name: Equipment
  - name: FormResponses
  - name: TimeEntries
  - name: Timesheets
  - name: JobFinancials
  - name: RevenueAttributions
externalDocs:
  description: Breezy FSM reporting guides and API reference
  url: https://developers.getbreezyapp.com
paths:
  /job-financials:
    get:
      tags:
        - JobFinancials
      summary: Page jobs with recorded costs and costing revenue
      description: >-
        One resource per owned job, identified by job ID and ordered by ID
        ascending. Complete saved costs, qualifying invoice facts and distinct
        assigned company members. Disabled or untracked costing has null totals
        while saved facts remain readable. Date filters refer to job creation or
        the company-local financial report date. No financial updated_since or
        snapshot.
      operationId: listJobFinancials
      parameters:
        - schema:
            type: array
            nullable: true
            items:
              type: string
              format: uuid
            minItems: 1
            maxItems: 100
            default: null
            description: >-
              Repeat ids for a bounded ID set. Valid foreign or missing IDs
              contribute no list rows.
          required: false
          style: form
          explode: true
          name: ids
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: >-
              Maximum parent records or report rows. Complete children are
              always included.
          required: false
          description: >-
            Maximum parent records or report rows. Complete children are always
            included.
          name: limit
          in: query
        - schema:
            type: string
            nullable: true
            minLength: 1
            default: null
            description: >-
              Repeat the original filters; any valid page size may continue.
              Foreign-company, tampered or mismatched cursors return
              INVALID_CURSOR.
          required: false
          description: >-
            Repeat the original filters; any valid page size may continue.
            Foreign-company, tampered or mismatched cursors return
            INVALID_CURSOR.
          name: cursor
          in: query
        - schema:
            type: string
            nullable: true
            format: date-time
            default: null
            description: Inclusive creation instant.
          required: false
          description: Inclusive creation instant.
          name: created_from
          in: query
        - schema:
            type: string
            nullable: true
            format: date-time
            default: null
            description: Exclusive creation instant.
          required: false
          description: Exclusive creation instant.
          name: created_before
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: account_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: business_unit_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: job_type_id
          in: query
        - schema:
            type: string
            nullable: true
            enum:
              - SERVICE
              - MAINTENANCE
              - ESTIMATE_REPAIR
              - ESTIMATE_REPLACE
              - INSTALL
              - WARRANTY
              - CALLBACK
              - SALES
              - UNKNOWN
              - null
          required: false
          name: job_class
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
            description: >-
              A validated assigned member. Selects distinct jobs for job
              financials/profitability and only that member for the
              participation report.
          required: false
          description: >-
            A validated assigned member. Selects distinct jobs for job
            financials/profitability and only that member for the participation
            report.
          name: team_member_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: location_id
          in: query
        - schema:
            type: string
            nullable: true
            format: date
            default: null
            description: Inclusive company-local job financial report date.
          required: false
          description: Inclusive company-local job financial report date.
          name: report_from
          in: query
        - schema:
            type: string
            nullable: true
            format: date
            default: null
            description: Exclusive company-local job financial report date.
          required: false
          description: Exclusive company-local job financial report date.
          name: report_before
          in: query
        - schema:
            type: string
            nullable: true
            enum:
              - NOT_TRACKED
              - TRACKED
              - null
          required: false
          name: tracking_status
          in: query
        - schema:
            type: string
            nullable: true
            enum:
              - UNVERIFIED
              - VERIFIED
              - null
          required: false
          name: verification_status
          in: query
      responses:
        '200':
          description: Successful read. Clients ignore unrecognized response fields.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobFinancialsPage'
              example:
                data:
                  - id: 11111111-1111-4111-8111-000000000501
                    number: '200'
                    account:
                      id: 11111111-1111-4111-8111-000000000101
                      name: Example Household
                    location_id: 11111111-1111-4111-8111-000000001107
                    business_unit:
                      id: 11111111-1111-4111-8111-000000000201
                      name: Service
                    job_type:
                      id: 11111111-1111-4111-8111-000000000301
                      name: HVAC Service
                    job_class: SERVICE
                    participants:
                      - id: 11111111-1111-4111-8111-000000000401
                        name: Alex Example
                    created_at: '2026-08-19T16:00:00Z'
                    report_date: '2026-08-20'
                    report_date_basis: INVOICE_ISSUED
                    costing:
                      enabled: true
                      tracking_status: TRACKED
                      verification_status: VERIFIED
                      job_type_included: true
                    currency: USD
                    totals:
                      revenue_cents: 130000
                      labor_cost_cents: 6000
                      parts_cost_cents: 24000
                      equipment_cost_cents: 0
                      misc_cost_cents: 0
                      other_cost_cents: 0
                      total_cost_cents: 30000
                      gross_profit_cents: 100000
                      gross_margin: 0.7692
                    invoices:
                      - id: 11111111-1111-4111-8111-000000000601
                        number: '1001'
                        status: OPEN
                        issued_at: '2026-08-20T16:00:00Z'
                        subtotal_cents: 100000
                      - id: 11111111-1111-4111-8111-000000000602
                        number: '1002'
                        status: PAID
                        issued_at: '2026-09-02T16:00:00Z'
                        subtotal_cents: 30000
                    cost_entries:
                      - id: 11111111-1111-4111-8111-000000001501
                        category: labor
                        source: manual
                        name: Recorded service labor
                        quantity: 120
                        quantity_unit: minute
                        unit_cost_cents: 3000
                        total_cents: 6000
                        labor_activity: On Site
                        misc_category: null
                        pricebook_item_id: null
                        created_at: '2026-09-08T19:00:00Z'
                        updated_at: '2026-09-08T19:00:00Z'
                      - id: 11111111-1111-4111-8111-000000001502
                        category: parts
                        source: invoice
                        name: Recorded replacement part
                        quantity: 2
                        quantity_unit: unit
                        unit_cost_cents: 12000
                        total_cents: 24000
                        labor_activity: null
                        misc_category: null
                        pricebook_item_id: null
                        created_at: '2026-09-08T19:00:00Z'
                        updated_at: '2026-09-08T19:00:00Z'
                pagination:
                  next_cursor: null
                meta:
                  request_id: 11111111-1111-4111-8111-000000009999
                  generated_at: '2026-09-08T19:00:00Z'
                  timezone: America/Los_Angeles
        '400':
          description: >-
            Malformed input, unknown query parameter, unsupported combination or
            invalid cursor.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST
                  message: end_date must be later than start_date
                  request_id: example-request
                  details: []
        '401':
          description: Missing, invalid or expired key, or invalid linked identity.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            WWW-Authenticate:
              schema:
                type: string
              example: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHENTICATED
                  message: A valid API key is required
                  request_id: example-request
                  details: []
        '404':
          description: >-
            Missing resource or resource outside the authenticated company. Same
            response for both.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
                  request_id: example-request
                  details: []
        '405':
          description: Write methods do not mutate business data and return 405.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Allow:
              schema:
                type: string
              example: GET, HEAD, OPTIONS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: METHOD_NOT_ALLOWED
                  message: This resource supports GET
                  request_id: example-request
                  details: []
        '429':
          description: Company request budget exhausted; retry after the indicated delay.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds before retrying.
              example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Request limit exceeded
                  request_id: example-request
                  details: []
        '500':
          description: >-
            Unexpected failure. Share request_id with support; no stack or
            provider secrets in response.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: Unable to complete request
                  request_id: example-request
                  details: []
      security:
        - apiKey: []
components:
  schemas:
    JobFinancialsPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobFinancials'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - pagination
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - INVALID_CURSOR
                - UNAUTHENTICATED
                - NOT_FOUND
                - METHOD_NOT_ALLOWED
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
            request_id:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - message
          required:
            - code
            - message
            - request_id
            - details
      required:
        - error
    JobFinancials:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The job ID; this resource has no separate persisted identity.
        number:
          type: string
        account:
          $ref: '#/components/schemas/Reference'
        location_id:
          type: string
          nullable: true
          format: uuid
        business_unit:
          $ref: '#/components/schemas/NullableReference'
        job_type:
          $ref: '#/components/schemas/NullableReference'
        job_class:
          $ref: '#/components/schemas/NullableJobClass'
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: >-
            Distinct currently associated company members with retained,
            consistently linked assignments. Includes inactive members and
            canceled visits; assignment is not proof of attendance.
        created_at:
          type: string
          format: date-time
          description: Job creation time, not creation of a financial snapshot.
        report_date:
          type: string
          format: date
          description: >-
            Company-local date of the earliest qualifying invoice issue time,
            otherwise job work completion, otherwise job creation. All job
            revenue and recorded costs use this date.
        report_date_basis:
          type: string
          enum:
            - INVOICE_ISSUED
            - WORK_COMPLETED
            - JOB_CREATED
        costing:
          type: object
          properties:
            enabled:
              type: boolean
            tracking_status:
              type: string
            verification_status:
              type: string
              description: >-
                Recorded current verification state; no verifier or verification
                timestamp is implied.
            job_type_included:
              type: boolean
              nullable: true
              description: >-
                Current job-type costing inclusion; null when the owned type is
                unavailable.
          required:
            - enabled
            - tracking_status
            - verification_status
            - job_type_included
        currency:
          type: string
          enum:
            - USD
        totals:
          type: object
          nullable: true
          properties:
            revenue_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Recorded pre-discount, pre-tax invoice subtotals in OPEN, PAID
                or UNCOLLECTABLE status.
            labor_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            parts_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            equipment_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            misc_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            other_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Recorded costs with an unrecognized category; retained in total
                costs.
            total_cost_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            gross_profit_cents:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            gross_margin:
              type: number
              nullable: true
              description: >-
                Gross profit / revenue, rounded to four decimal places; null at
                zero revenue. A fraction, not a percentage.
          required:
            - revenue_cents
            - labor_cost_cents
            - parts_cost_cents
            - equipment_cost_cents
            - misc_cost_cents
            - other_cost_cents
            - total_cost_cents
            - gross_profit_cents
            - gross_margin
          description: >-
            Unavailable when company costing is disabled or the job is not
            TRACKED. Saved entries and invoice facts remain readable. Unverified
            or excluded tracked jobs retain calculations.
        invoices:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              number:
                type: string
              status:
                type: string
                enum:
                  - OPEN
                  - PAID
                  - UNCOLLECTABLE
              issued_at:
                type: string
                nullable: true
                format: date-time
              subtotal_cents:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
            required:
              - id
              - number
              - status
              - issued_at
              - subtotal_cents
          description: >-
            Complete owned qualifying invoice facts; their recorded subtotals
            explain the costing revenue basis.
        cost_entries:
          type: array
          items:
            $ref: '#/components/schemas/JobCostEntry'
          description: >-
            Complete saved cost entries. Reads never populate or synchronize
            costs from time entries, wages, invoice lines or pricebook data.
      required:
        - id
        - number
        - account
        - location_id
        - business_unit
        - job_type
        - job_class
        - participants
        - created_at
        - report_date
        - report_date_basis
        - costing
        - currency
        - totals
        - invoices
        - cost_entries
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque continuation. Null ends traversal. Keep the same filters;
            page size may change.
      required:
        - next_cursor
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
        generated_at:
          type: string
          format: date-time
        timezone:
          type: string
      required:
        - request_id
        - generated_at
        - timezone
      description: >-
        Generation time and company timezone. generated_at is not a snapshot or
        synchronization token.
    Reference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
    NullableReference:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
    NullableJobClass:
      type: string
      nullable: true
      enum:
        - SERVICE
        - MAINTENANCE
        - ESTIMATE_REPAIR
        - ESTIMATE_REPLACE
        - INSTALL
        - WARRANTY
        - CALLBACK
        - SALES
        - UNKNOWN
        - null
    JobCostEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        category:
          type: string
          description: >-
            Recorded category, normally labor, parts, equipment or misc; legacy
            values are preserved.
        source:
          type: string
          description: >-
            Recorded source, normally manual, timesheet or invoice. This does
            not identify a worker or allocate revenue.
        name:
          type: string
        quantity:
          type: number
        quantity_unit:
          type: string
          enum:
            - minute
            - unit
        unit_cost_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Recorded hourly cost for labor; per-unit cost for other categories.
        total_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            PostgreSQL numeric rounding per entry: quantity / 60 × hourly cost
            for labor, quantity × unit cost otherwise. Half-cent ties round away
            from zero.
        labor_activity:
          type: string
          nullable: true
        misc_category:
          $ref: '#/components/schemas/NullableReference'
        pricebook_item_id:
          type: string
          nullable: true
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - category
        - source
        - name
        - quantity
        - quantity_unit
        - unit_cost_cents
        - total_cents
        - labor_activity
        - misc_category
        - pricebook_item_id
        - created_at
        - updated_at
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Existing Breezy API key. Grants all published reads in its associated
        company. No app permission scopes.

````