> ## Documentation Index > Fetch the complete documentation index at: https://hc.starbridge.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Bridge Rows > 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. ## OpenAPI ````yaml https://core-http2-157602306522.us-central1.run.app/external/public/swagger/documentation.yaml put /api/external/bridge/{bridgeId}/row openapi: 3.1.1 info: title: Starbridge External Public API version: '1.0' servers: - url: https://dashboard.starbridge.ai security: [] paths: /api/external/bridge/{bridgeId}/row: put: tags: - Bridges - External MCP - External API summary: List Bridge Rows description: >- 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. operationId: listBridgeRows parameters: - name: bridgeId in: path required: true schema: type: string - name: pageNumber in: query description: Page number, 1-based. Minimum 1. schema: type: integer default: '1' - name: pageSize in: query description: Page size. Must be > 0 and <= 100. Prefer <= 20. schema: type: integer default: '10' requestBody: description: >- Filtering, sorting, and free-text search parameters for bridge rows. Refer to examples for proper usage. content: application/json: schema: $ref: '#/components/schemas/ListBridgeRowsRequest' responses: '200': description: Paginated list of bridge rows content: application/json: schema: type: object required: - pageNumber - pageSize - totalItems - totalPages - result properties: pageNumber: type: integer pageSize: type: integer totalItems: type: integer totalPages: type: integer result: type: array items: $ref: '#/components/schemas/BridgeRowResponse' '400': description: Invalid request body or format '401': description: Missing or invalid authentication '403': description: Unauthorized to access resource or perform action '404': description: Resource not found '415': description: Unsupported media type or request body format '429': description: Rate limit exceeded '500': description: Internal server error security: - apiKey: [] components: schemas: ListBridgeRowsRequest: type: object title: ListBridgeRowsRequest properties: filters: oneOf: - $ref: '#/components/schemas/BridgeFilters' - type: 'null' sorts: type: - array - 'null' description: |2- 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. items: $ref: '#/components/schemas/RowSort' query: type: - string - 'null' description: Full-text search query examples: - filters: terms: - field: 79699ea1-b638-45b4-8b44-781d76eb88a1 operation: Equals value: some value - filters: terms: - field: 79699ea1-b638-45b4-8b44-781d76eb88a1 operation: Any value: - value A - value B query: search text - filters: terms: - field: 79699ea1-b638-45b4-8b44-781d76eb88a1 operation: Contains value: partial - field: a1b2c3d4-e5f6-7890-abcd-ef1234567890 operation: IsNotEmpty sorts: - column: 79699ea1-b638-45b4-8b44-781d76eb88a1 direction: ASC - filters: terms: - field: 79699ea1-b638-45b4-8b44-781d76eb88a1 operation: HasCellStatus value: - Not Processed - Processing - Processed default: {} BridgeRowResponse: type: object title: BridgeRowResponse required: - rowId - bridgeId - createdAt - updatedAt - status - columns properties: rowId: type: string description: Unique identifier for the row format: uuid name: type: - string - 'null' description: Optional name or title of the row bridgeId: type: string description: UUID of the bridge this row belongs to format: uuid createdAt: type: string description: Timestamp when the row was created (added to the bridge). updatedAt: type: string description: |2- 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: type: string description: Current processing status of the row enum: - NotProcessed - Queued - Processing - Processed - Failed - Skipped buyerId: type: - string - 'null' description: UUID of the buyer associated with this row, if any format: uuid organizerId: type: - string - 'null' description: UUID of the conference organizer associated with this row, if any format: uuid entity: oneOf: - $ref: '#/components/schemas/BridgeRowEntityRef' - type: 'null' columns: type: object additionalProperties: $ref: '#/components/schemas/BridgeRowColumnValueResponse' BridgeFilters: type: object title: BridgeFilters description: |2- 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. properties: terms: type: array items: $ref: '#/components/schemas/BridgeFiltersTerm' RowSort: type: object title: RowSort required: - column - direction properties: column: type: string direction: type: string enum: - ASC - DESC BridgeRowEntityRef: type: object title: BridgeRowEntityRef description: >- Reference to the underlying entity (id + type) this row represents, when available. required: - type - id properties: type: type: string description: Kind of entity `id` refers to (e.g. Conference, Buyer, Opportunity). enum: - RFP - Meeting - Purchase - Buyer - Contact - Signal - Conference - JobChange - SequenceBuyer - SequenceContact - SequenceJobChange id: type: string description: >- 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. BridgeRowColumnValueResponse: type: object title: BridgeRowColumnValueResponse properties: value: description: >- Any JSON value - can be a string, number, boolean, object, array, or null status: type: - string - 'null' description: Processing status of this column value enum: - NotProcessed - Queued - Processing - Processed - Failed - Skipped processedAt: type: - string - 'null' description: Timestamp when the value was successfully processed BridgeFiltersTerm: type: object title: BridgeFiltersTerm description: |2- A single filter predicate of the form ` `, evaluated against one bridge row. Multiple terms in a `BridgeFilters` are combined with logical AND. ────────────────────────────────────────────────────────────────────────────────────── 1) Pick a `column`.: (A) A column's `columnId` UUID, returned by `getBridgeColumnMetadata`. Always a bare UUID string — never the column's `key`, `name`, or any prefixed reference. The value type must match that column's declared format (see `BridgeRowColumnValueResponse.value`). 2) Pick an `operation` — its category determines the required shape of `value`: category | operations | value shape -------------------|-----------------------------------------------------------------------------------------------|---------------------------------------- scalar | Equals, DoesNotEqual, Contains, DoesNotContain, GreaterThan, LessThan | one JSON primitive (string/number/bool) array | Any, None, ContainsAny, ContainsAll, ContainedBy, NotContainedBy | JSON array of primitives presence | IsEmpty, IsNotEmpty | null / omitted column-status | HasCellStatus, HasLookupStatus, HasLastSyncStatus, HasSyncStatusHistory | JSON array of status strings | (REQUIRE `field` to be a column UUID — on a common key they silently degrade to Any/ContainsAny | against the row-level field, which is almost certainly wrong.) | See `BridgeFilterOperation` for the per-operation semantics. 3) `value` must ALSO be type-compatible with the field: - common-field types are listed in the table above - for column fields, match the column's declared `fieldFormat` - primitive inside an array follows the same rule (e.g. `Any` on `buyerId` takes an array of UUID strings) ────────────────────────────────────────────────────────────────────────────────────── Common gotcha — filtering by `status`: `status` is a single-valued scalar. Do NOT wrap values in an array for `Equals`. Match exactly one status: { "field": "status", "operation": "Equals", "value": "Processed" } Match several statuses (OR within the term): { "field": "status", "operation": "Any", "value": ["Processed", "Failed"] } WRONG — array with a scalar op silently matches nothing: { "field": "status", "operation": "Equals", "value": ["Processed"] } // ✗ WRONG — bare string with an array op: { "field": "status", "operation": "Any", "value": "Processed" } // ✗ Common gotcha — column-cell status filtering: To filter by a column's per-cell processing status, use `HasCellStatus` with the column's `columnId` and an array of status labels: { "field": "", "operation": "HasCellStatus", "value": ["Processed", "Failed"] } The server rewrites this into a phase-scoped query on the cell's status/value status fields — you never address those sub-fields directly from the client. required: - field - operation properties: field: type: string description: |2- 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: type: string description: |2- 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. enum: - Equals - DoesNotEqual - Contains - DoesNotContain - GreaterThan - LessThan - IsEmpty - IsNotEmpty - Any - None - ContainsAny - ContainsAll - ContainedBy - NotContainedBy - HasCellStatus - HasLookupStatus - HasLastSyncStatus - HasSyncStatusHistory value: description: |2- Operand for the comparison. Polymorphic — shape is driven by `operation`: - scalar ops (Equals, DoesNotEqual, Contains, DoesNotContain, GreaterThan, LessThan) → one JSON primitive (string / number / boolean) - array ops (Any, None, ContainsAny, ContainsAll, ContainedBy, NotContainedBy, HasCellStatus, HasLookupStatus, HasLastSyncStatus, HasSyncStatusHistory) → a JSON array of primitives; use an array even for a single element - presence ops (IsEmpty, IsNotEmpty) → null or omitted The primitive type must also match the field's underlying type: strings for text / URL / enum / date / UUID / ISO-8601 fields, numbers for numeric fields, booleans for boolean columns, and JSON objects for object-typed columns. securitySchemes: apiKey: scheme: bearer description: HTTP Bearer Authentication type: http ````