Pagination, sorting, expansion

Last updated Jun 14, 2026

List endpoints return a cursor-paginated envelope. The envelope shape is stable across every list endpoint — swap data[] for the resource you're after and the rest is identical.

{
  "object": "list",
  "data": [ /* up to `limit` items */ ],
  "has_more": true,
  "url": "/v1/entities",
  "next_cursor": "ent_Nq3KcAbc"
}

Page forward with ?starting_after=<id>; backward with ?ending_before=<id>. Default limit is 10, max 100. See pagination.

Matter uses cursor pagination on every collection endpoint. The list envelope includes next_cursor for explicit cursor callers.

Pagination

GET /v1/entities?limit=10&starting_after=ent_Nq3KcAbc

starting_after and ending_before are mutually exclusive.

Response:

{
  "object": "list",
  "data": [ /* resources */ ],
  "has_more": true,
  "url": "/v1/entities",
  "next_cursor": "cur_PqB5fG7K"
}

Either pass the last data[].id as starting_after on the next page, or pass next_cursor — both work.

Sorting

?sort=-created,legal_name

• Leading - = descending, no prefix = ascending.
• Comma-separated for multi-key sort.
• Default is -created (reverse chronological).

Filtering

Per-endpoint filters as query parameters. Each endpoint documents its available filter keys; filters are named and typed explicitly rather than a generic DSL.

?status=active&jurisdiction=US-DE&portfolio_id=pf_...

Metadata filtering

Lists accept ?metadata[key]=value for exact-match filtering on metadata keys:

?metadata[fund]=fund-iii&metadata[environment]=production

Multiple pairs AND together. Prefer sparse keys — every filtered key incurs an index cost. For boolean composition (OR, ranges, substring), use the full search DSL at POST /v1/<resource>/search — see /api/tooling/search.

Expansion with expand[]

By default, related resources are referenced by ID. Use expand[] to inline the full resource:

?expand[]=tax_profile&expand[]=cap_table&expand[]=cap_table.share_classes

• Array-style: expand[]=a&expand[]=b.
• Dot-notation for nested: expand[]=cap_table.share_classes.
• Max depth 4.
• Only fields marked x-matter-expandable: true on their schema are expandable — attempting to expand an unrelated field returns 400.

Expansion works on retrieve, create, update, and list endpoints. On list responses, expansion begins at data. implicitly.

Field selection with fields[]

Narrow the response to only the fields you need:

?fields[]=id&fields[]=status&fields[]=jurisdiction

• Array-style like expand[]: fields[]=id&fields[]=status.
• id and object are always included — the shape is preserved even when you don't list them.
• Dot-notation is not supported here; compose with expand[] when nested shape is needed.

Designed for agent runtimes that spend tokens on list responses. A 500-entity list with fields[]=id&fields[]=status returns ~2 KB instead of ~2 MB. Caching treats each projection as a distinct variant, so stick to a small number of projections you actually need.

dry_run: true

Every mutation accepts ?dry_run=true as a query parameter. Returns the would-be resource plus any cascaded resources and a fee estimate, without side effects. See test mode for typical CI patterns.