---
title: "List Bridge Rows"
method: PUT
path: "/api/external/bridge/{bridgeId}/row"
tags: ["Bridges", "External MCP", "External API"]
---

# List Bridge Rows

`PUT /api/external/bridge/{bridgeId}/row`

List the rows of a single Bridge — the concrete matches the Bridge has produced — with optional filtering, sorting, and full-text search. Each row carries a processing status, optional buyer/organizer association, an `updatedAt` timestamp, and the per-column values populated for that match. The per-row `columns` map is keyed by the human-readable column name (not by columnId), and values are polymorphic per the column's `fieldFormat` (string / number / boolean / object / null).

Prefer narrowing server-side with `filters`, `sorts`, and `query` in the request body over scanning every page.

For any column-targeted filter or sort — including Match Score, Match reasoning,
and any user-defined column — first call `getBridgeColumnMetadata` to obtain that
column's `columnId` UUID and pass it as `BridgeFilters.terms[].field` or
`RowSort.column`. The column's display name, `key`, or any prefixed reference is
NOT a valid value. A small set of common entry-level fields (`status`, `buyerId`,
`opportunityId`, `entryName`, `triggeredAt`) is also accepted for filtering.
Sort or filter columns that are not mapped on the server return 400. See
`ListBridgeRowsRequest` for the full schema of supported filter terms,
operations, and sort columns.


To paginate, start at `pageNumber=1` and increment until `pageNumber == totalPages`.

Note on consistency: the data backing search/sort/filter is maintained separately from the row values returned here, and the two can briefly drift apart — especially while the service is under heavy load. As a result, recent changes (new rows, status changes, updated column values, `updatedAt`, etc.) may not be reflected in listing, sorting, or filtering immediately; they usually become consistent within a short time. If a just-changed row does not appear where you expect, retry shortly.

## Path parameters

- `bridgeId` string, required

## Query parameters

- `pageNumber` integer
- `pageSize` integer

## Request body

- ListBridgeRowsRequest
  - `filters` BridgeFilters — Filter criteria for bridge rows. All `terms` are combined with logical AND — a row must satisfy every term to be included. Provide an empty `terms` list (or omit `filters`) to return all rows.
    - `terms` BridgeFiltersTerm[]
      - `field` string, required — What to filter on. Exactly one of: - a bridge column's `columnId` UUID (returned by `getBridgeColumnMetadata`) as a bare UUID string. PREFER THIS for anything that appears as a column on the Bridge — Match Score, Match reasoning, and any user-defined column live here. Using the column's `key`, `name`, or any compound reference is undefined behavior. - a common entry-field key, limited to: `status`, `buyerId`, `opportunityId`, `entryId`, `entryName`, `triggeredAt`, `op:added_date`, `bridge:entry_url`, `adminActionCrmMatch`. Other internal field keys are not exposed and return 400 if used.
      - `operation` 'Equals' | 'DoesNotEqual' | 'Contains' | 'DoesNotContain' | 'GreaterThan' | 'LessThan' | 'IsEmpty' | 'IsNotEmpty' | 'Any' | 'None' | 'ContainsAny' | 'ContainsAll' | 'ContainedBy' | 'NotContainedBy' | 'HasCellStatus' | 'HasLookupStatus' | 'HasLastSyncStatus' | 'HasSyncStatusHistory', required — Comparison operator. Its category dictates the required shape of `value`: scalar ops take a single primitive, array ops take a JSON array, presence ops take null, column-status ops (Has…) take a status array and require `field` to be a column UUID. See the `BridgeFilterOperation` enum for full details.
      - `value` unknown
  - `sorts` RowSort[], nullable — Sort specification for rows. For each sort term, `column` should be a bridge column's `columnId` UUID — call `getBridgeColumnMetadata` to look it up. The column's display name, `key`, or any prefixed reference is not a valid value. A small set of common entry-level fields (`entryId`, `entryName`, `triggeredAt`) is also accepted but discouraged. The synthetic column `rowUpdatedAt` sorts by when the row was last updated — sort `DESC` to poll for recently-changed rows, matching the `updatedAt` field in the response. Sort columns that are not mapped on the server return 400.
    - `column` string, required
    - `direction` 'ASC' | 'DESC', required
  - `query` string, nullable — Full-text search query

## Response `200`

Paginated list of bridge rows

- object
  - `pageNumber` integer, required
  - `pageSize` integer, required
  - `totalItems` integer, required
  - `totalPages` integer, required
  - `result` BridgeRowResponse[], required
    - `rowId` string, uuid, required — Unique identifier for the row
    - `name` string, nullable — Optional name or title of the row
    - `bridgeId` string, uuid, required — UUID of the bridge this row belongs to
    - `createdAt` string, required — Timestamp when the row was created (added to the bridge).
    - `updatedAt` string, required — Timestamp when the row was last updated. This is a technical last-updated field: in addition to meaningful changes (status, column values), non-meaningful changes such as a bulk re-sync or maintenance can also advance it. Sort by `rowUpdatedAt` to page through recently-changed rows.
    - `status` 'NotProcessed' | 'Queued' | 'Processing' | 'Processed' | 'Failed' | 'Skipped', required — Current processing status of the row
    - `buyerId` string, uuid, nullable — UUID of the buyer associated with this row, if any
    - `organizerId` string, uuid, nullable — UUID of the conference organizer associated with this row, if any
    - `entity` BridgeRowEntityRef — Reference to the underlying entity (id + type) this row represents, when available.
      - `type` 'RFP' | 'Meeting' | 'Purchase' | 'Buyer' | 'TopBuyer' | 'Contact' | 'Signal' | 'Conference' | 'JobChange' | 'SequenceBuyer' | 'SequenceContact' | 'SequenceJobChange' | 'VendorPresence' | 'ProductCompetitorPresence' | 'CompanionPresence', required — Kind of entity `id` refers to (e.g. Conference, Buyer, Opportunity).
      - `id` string, required — Identifier of the underlying entity. Pass to entity-specific tools (e.g. opportunity line items, file downloads) to fetch detail beyond the bridge's columns.
    - `columns` object, required

## Other responses

- `400` — Invalid request body or format
- `401` — Missing or invalid authentication
- `403` — Unauthorized to access resource or perform action
- `404` — Resource not found
- `415` — Unsupported media type or request body format
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.dev/starbridge/apis/starbridge-external-public-api.md) · [All operations](https://skmtc.dev/starbridge/apis/starbridge-external-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/starbridge/starbridge-external-public-api/revisions/dc7faf636b78/schema)