> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # List Plaid connection events > List recorded Plaid connection events for a business, newest first by default. ## Access Use a platform access token for the business's client or a business-scoped token for that business. ## Interpret the fields * **`event_type` and `details`** describe what happened. Start with the [event types](#event-types) below to distinguish failures from normal activity. * **`connection_type` and `connection_id`** identify a Layer item or processor-token record. **`plaid_account_id`** is a Layer account UUID. These are not Plaid IDs or token values. * **`source` and `actor`** show the event's origin and recorded actor; `actor` can be absent. **`created_at`** is when Layer recorded it. * **`webhook_type` and `webhook_code`** identify a Plaid notification. Read them alongside `details` before deciding whether it reports an error. Events have no attempt or Link session ID. When `connection_id` is absent, investigate using the business and `created_at`. ## Event types ### Link and connection setup * **`LINK_TOKEN_CREATED` — Normal setup.** Layer created a Link token. `details` is `standard` or `update`; update mode includes the existing connection ID. This does not mean the user connected an account. * **`LINK_CLIENT_OUTCOME` — Client report.** `details` contains `COMPLETED`, `EXITED`, or `ERROR`, optionally followed by `:error_code`, such as `EXITED:INVALID_CREDENTIALS`. An exit can be cancellation, not a failure. `COMPLETED` is not confirmation of token exchange or sync. These events have no connection ID. * **`LINK_EXCHANGE_SUCCEEDED` — Exchange succeeded.** Layer exchanged the public token and added the item. Use `connection_id` to follow later sync events; synchronization can still fail. * **`LINK_EXCHANGE_FAILED` — Exchange failed.** `details` contains the exception class name, not necessarily Plaid's underlying error code. No connection ID is recorded; use the business, timestamp, and exception name to investigate. * **`LINK_UPDATE_COMPLETED` — Update notification.** The client called Layer's connection-status update endpoint. Layer records this business-level event before syncing; it does not confirm repair or successful sync. No connection ID is recorded. * **`PROCESSOR_TOKEN_ATTACHED` — Normal setup.** Layer stored a processor token for the business. Use `connection_id` to follow that token's events. Attachment does not confirm that the token can sync. ### Sync, webhooks, and repair * **`WEBHOOK_RECEIVED` — Notification received.** Not inherently an error. Check `webhook_type` and `webhook_code`; `details` can contain JSON text with an error, reason, disconnect time, or consent-expiration time. Use the connection and account IDs to locate the affected records. Receipt does not confirm successful processing. * **`SYNC_FAILED` — Synchronization failed.** `details` contains JSON text with the exception name and, when available, Plaid error information, HTTP status, or endpoint. Investigate the connection ID and these diagnostics; a sync failure alone does not establish that credentials need repair. * **`CONNECTION_NEEDS_REPAIR` — Repair required.** Layer marked the connection or account as needing repair. `details` can be `persistent`, but is not a root-cause code. Check `source`, the connection/account IDs, and nearby webhook or sync errors for context. * **`CONNECTION_REPAIRED` — Repair state cleared.** Layer cleared the connection's repair flag. Use `source` and `connection_id` to investigate the transition. This does not guarantee that all data has synchronized. ### Connection lifecycle * **`CONNECTION_ARCHIVED` — Lifecycle change.** Layer archived an item or processor-token record. Check `actor`, `source`, and `connection_id`; archival can also follow a disconnect or account archival. * **`CONNECTION_DISCONNECTED` — Lifecycle change.** Layer marked an item as disconnected and then archives it. Use `connection_id` to follow the related archive event. * **`CONNECTION_REACTIVATED` — Lifecycle change.** Layer cleared an item's or processor token's archived state. Check `source`, `actor`, and `connection_id`; reactivation alone does not confirm healthy credentials or successful sync. ## Filter and paginate Use `event_types=LINK_EXCHANGE_FAILED,SYNC_FAILED` to focus on exchange and sync failures. Omit `event_types` when you need surrounding lifecycle events. Filters combine with AND; the `event_types` values match any listed type. Filtering by a connection or account excludes events that have no matching ID. Results default to newest first. While `meta.pagination.has_more` is `true`, pass `meta.pagination.cursor` with the same filters and sort parameters. A cursor can still be present on the last page. Set `show_total_count=true` to include the total number of matching events. ## OpenAPI ````yaml get /v1/businesses/{businessId}/plaid/connection-events openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/plaid/connection-events: get: summary: List Plaid connection events description: >- List recorded Plaid connection events for a business, newest first by default. operationId: business.plaid.listConnectionEvents parameters: - name: businessId in: path required: true description: >- Layer business UUID. Platform credentials can access businesses belonging to their client; business credentials can access their own business. schema: type: string format: uuid - name: connection_type in: query description: >- Filter by connection kind. Filters combine with AND; events with no connection kind will not match. schema: type: string enum: - ITEM - PROCESSOR_TOKEN - name: connection_id in: query description: >- Layer UUID of the Plaid item or processor-token record, not Plaid's item ID or a token value. schema: type: string format: uuid - name: account_id in: query description: >- Layer UUID of the Plaid account. Matches events explicitly associated with that account, not all events for its connection. schema: type: string format: uuid - name: event_types in: query description: >- Filter by case-sensitive event types, comma-separated or repeated. See [Event types](#event-types) for diagnostic guidance. style: form explode: false schema: type: array items: $ref: '#/components/schemas/PlaidConnectionEventType' - name: limit in: query description: Maximum number of events per page. schema: type: integer minimum: 1 maximum: 1000 default: 100 - name: cursor in: query description: >- Pass meta.pagination.cursor from the previous page while has_more is true. Keep filters and sort parameters unchanged. schema: type: string - name: sort_by in: query schema: type: string enum: - created_at default: created_at - name: sort_order in: query description: >- Order by created_at. Ties are ordered by event UUID ascending in either direction. schema: type: string enum: - ASC - DESC default: DESC - name: show_total_count in: query description: >- Include the total number of matching events across all pages in meta.pagination.total_count. schema: type: boolean default: false responses: '200': description: >- Recorded events and pagination metadata. Returns an empty data array when no events match. content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/ApiPlaidConnectionEvent' meta: type: object required: - pagination properties: pagination: $ref: '#/components/schemas/PaginationMetadata' example: data: - type: Plaid_Connection_Event id: 9340d882-75cc-4224-9820-cc8634856d84 event_type: LINK_EXCHANGE_FAILED source: USER actor: USER connection_type: null connection_id: null plaid_account_id: null webhook_type: null webhook_code: null details: PlaidExchangePublicTokenError created_at: '2026-11-01T12:00:00Z' meta: pagination: sort_by: created_at sort_order: DESC cursor: opaque-cursor has_more: false total_count: 1 '400': description: Invalid filter, sort, limit, or cursor. '401': description: >- Missing or invalid credentials, including a business token that does not authenticate for the requested business. '404': description: >- Business not found or not accessible to the authenticated platform client. components: schemas: PlaidConnectionEventType: type: string description: >- Recorded event kind. See [Event types](#event-types) for diagnostic guidance. enum: - LINK_TOKEN_CREATED - LINK_EXCHANGE_SUCCEEDED - LINK_EXCHANGE_FAILED - LINK_CLIENT_OUTCOME - LINK_UPDATE_COMPLETED - WEBHOOK_RECEIVED - SYNC_FAILED - CONNECTION_NEEDS_REPAIR - CONNECTION_REPAIRED - PROCESSOR_TOKEN_ATTACHED - CONNECTION_ARCHIVED - CONNECTION_DISCONNECTED - CONNECTION_REACTIVATED ApiPlaidConnectionEvent: type: object required: - type - id - event_type - source - created_at properties: type: type: string enum: - Plaid_Connection_Event id: type: string format: uuid description: Layer event UUID. event_type: $ref: '#/components/schemas/PlaidConnectionEventType' source: type: string enum: - USER - PLAID_WEBHOOK - SYSTEM description: Origin of the event. actor: type: string nullable: true enum: - USER - AI_BOOKKEEPER - MANUAL_BOOKKEEPER - SYSTEM - UNKNOWN - null description: Actor recorded for the event, when available. connection_type: type: string nullable: true enum: - ITEM - PROCESSOR_TOKEN - null connection_id: type: string format: uuid nullable: true description: Layer item or processor-token UUID, when associated with the event. plaid_account_id: type: string format: uuid nullable: true description: >- Layer Plaid account UUID, when associated with the event. Filter using account_id. webhook_type: type: string nullable: true description: Plaid webhook type, when recorded. webhook_code: type: string nullable: true description: Plaid webhook code, when recorded. details: type: string nullable: true description: >- Event-specific diagnostic text; some event types store JSON inside this string. See Event types for interpretation. created_at: type: string format: date-time description: Time Layer recorded the event. PaginationMetadata: type: object description: >- Cursor-based pagination metadata returned alongside paginated list responses. properties: sort_by: type: string nullable: true description: Field the result set is sorted by. sort_order: type: string enum: - ASC - DESC description: Sort direction applied to the result set. example: ASC cursor: type: string nullable: true description: >- Opaque pagination cursor. Pass it using the query parameter documented for the endpoint only when has_more is true. A cursor can be present on the last page. has_more: type: boolean description: Whether additional pages are available after the current one. total_count: type: integer format: int64 nullable: true description: Total number of records across all pages, when available. required: - sort_by - sort_order - cursor - has_more securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.