# List Stages

`lawmatics_list-stages` · Lawmatics MCP tool · Pipeline Stages

List pipeline stages from Lawmatics with optional pagination, filtering, and sorting. Rows carry stage attributes and a `relationships` envelope with a to-one {id,type} pointer to the parent pipeline; use get-stage for the full record including the prospects in each stage.

## Input

- **page** `integer` (> 0) — Page number (1-based)
- **filter** `object` — Optional single-field filter; one filter at a time
  - **field** `string` (required, enum: "pipelineId") — Field to filter on; only 'pipelineId' is filterable
  - **operator** `string` (enum: "=", "!=", "<", "<=", ">", ">=", "like", "ilike", "null", "not_null", default: "=") — Comparison operator; defaults to '=' (pipelineId is a numeric id — 'ilike' is rejected by the API)
  - **value** `string` (required) — Value to compare against (ignored for null / not_null operators)
- **sortBy** `string` (enum: "id", "created_at", "updated_at", "name", "color") — Column to sort by
- **sortOrder** `string` (enum: "asc", "desc") — Sort direction; ascending or descending

## Output

- **stages** `array` (required) — Stages on this page of results. Rows carry stage attributes and a to-one pipeline relationship pointer; use get-stage for the full record incl. prospects
  - **[]** `object`
    - **id** `string` (required) — Lawmatics stage ID
    - **name** `string` (required) — Stage name
    - **color** `string | null` (required) — Stage display color as a hex string (e.g. '#757F8F'); null if unset
    - **order** `number | null` (required) — Position of the stage within its pipeline; null if unset
    - **createdAt** `string | null` (required) — When the stage was created, as an ISO 8601 timestamp; null if unset
    - **updatedAt** `string | null` (required) — When the stage was last updated, as an ISO 8601 timestamp; null if unset
    - **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. List rows carry the to-one pipeline pointer only; use get-stage for the full envelope incl. to-many prospects.
      - **pipeline** `object | null` (required) — Parent pipeline pointer; null when unset
        - **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 | null` (required) — Pagination metadata from the API response; null when the endpoint returns no meta envelope
  - **totalPages** `number | null` (required) — Total number of pages available; null if not reported
  - **limitPerPage** `number | null` (required) — Maximum stages returned per page; null if not reported
  - **totalEntries** `number | null` (required) — Total number of stages across all pages; null if not reported