# List Expenses

`lawmatics_list-expenses` · Lawmatics MCP tool · Expenses

List expenses from Lawmatics with optional pagination, filtering, and sorting. Filter by the attached matter/contact id, the associated user id, or expense fields like billable and created_at. Each row carries a `relationships` envelope of to-one {id,type} pointers (the attached matter or contact, staff and creating users, billing expense type, invoice).

## Input

- **page** `integer` (> 0) — Page number (1-based)
- **filter** `object` — Optional single-field filter; one filter at a time
  - **field** `string` (required, enum: "contactable_id", "contactable_type", "user_id", "billable", "description", "created_at", "updated_at") — Field to filter on: contactable_id (numeric id of the matter/contact the expense is attached to), contactable_type (STORED record type — use Prospect for matter-attached and Contact for contact-attached expenses; case-sensitive, and the write-side 'Matter' literal does NOT match), user_id (numeric id of the associated firm user), billable (true/false), description (text), created_at, or updated_at (dates)
  - **operator** `string` (enum: "=", "!=", "<", "<=", ">", ">=", "like", "ilike", "null", "not_null") — Comparison operator. Omit to use the Lawmatics per-field default (= for ids/booleans/dates, ilike for strings). Use = for id fields and a range operator (e.g. >) for created_at
  - **value** `string` (required) — Value to compare against (ignored for null / not_null operators)
- **sortBy** `string` (enum: "id", "created_at", "updated_at") — Column to sort by
- **sortOrder** `string` (enum: "asc", "desc") — Sort direction; ascending or descending

## Output

- **expenses** `array` (required) — Expenses on this page of results
  - **[]** `object`
    - **id** `string` (required) — Unique ID of the expense
    - **description** `string | null` (required) — Description of the expense; null if unset
    - **costCents** `number | null` (required) — Expense cost in integer cents (e.g. 50000 = $500.00); null if not reported
    - **billable** `boolean | null` (required) — Whether the expense is billable; null if not reported
    - **rateFlatFee** `boolean | null` (required) — Whether the expense is billed as a flat fee; null if not reported
    - **rateCents** `number | null` (required) — Billing rate in integer cents; null if not reported
    - **rateCurrency** `string | null` (required) — ISO currency code of the billing rate (e.g. USD); null if not reported
    - **duration** `number | null` (required) — Duration value as returned by the API (expenses share Lawmatics' time-entry storage model); null if not reported
    - **durationRounded** `number | null` (required) — Duration rounded to the firm's billing increment; null if not reported
    - **startedAt** `string | null` (required) — ISO 8601 timestamp the expense timer started; null if unset or omitted
    - **completedAt** `string | null` (required) — ISO 8601 timestamp the expense timer completed; null if unset or omitted
    - **createdAt** `string | null` (required) — When the expense was created, as an ISO 8601 timestamp; null if unknown
    - **updatedAt** `string | null` (required) — When the expense was last updated, as an ISO 8601 timestamp; null if unknown
    - **relationships** `object` (required) — To-one JSON:API relationship pointers as {id,type} stubs. Not materialized — follow a pointer by calling that resource's own tool (e.g. type 'user' -> get-user, type 'prospect' -> get-matter, type 'contact' -> get-contact, type 'invoice' -> get-invoice).
      - **staff** `object | null` (required) — Pointer to the firm user the expense is attributed to; null when unattributed
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **createdBy** `object | null` (required) — Pointer to the firm user who created the record; null when unattributed
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **expenseType** `object | null` (required) — Pointer to the billing expense type categorizing this expense; null when uncategorized
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **contactable** `object | null` (required) — Pointer to the record the expense is attached to; type is "prospect" for a matter or "contact" for a contact; null when unattached
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
      - **invoice** `object | null` (required) — Pointer to the invoice this expense is billed on; null when uninvoiced
        - **id** `string` (required) — ID of the referenced Lawmatics record
        - **type** `string` (required) — JSON:API record class of the reference (e.g. "user", "contact", "prospect", "firm"); resolve it by calling that resource's own get/find tool — this pointer is not materialized
- **pagination** `object` (required) — Pagination metadata derived from the API `meta` envelope
  - **totalPages** `number | null` (required) — Total number of pages available; null if not reported
  - **limitPerPage** `number | null` (required) — Maximum expenses returned per page; null if not reported
  - **totalEntries** `number | null` (required) — Total number of expenses across all pages; null if not reported