Connection Health Monitoring

This guide covers what can affect the health and data completeness of a connection, how Terminal surfaces these events, and what you can do to monitor and manage them. It complements Data Replication and the API sync guide, which cover the happy path for getting data out of Terminal.

Overview

A connection’s health can be affected by several categories of events, ranging from full disconnects that require fleet action to subtle ingestion-level issues that may only impact specific data types. Terminal provides tools across the API, webhooks, and dashboard to help you monitor and respond to each.

Category	Data Impact	Action Required	How It Surfaces
Disconnects	All data ingestion stops	Fleet must reconnect	Connection status, webhooks, email notifications
Sync failures	Data temporarily stale	Handled by Terminal	Sync status, webhooks
Ingestion issues	Specific data may be incomplete	Varies	Issues API, webhooks, dashboard

Connection Disconnects

A disconnect occurs when a connection’s authentication is no longer valid. This is the most impactful health event because all data ingestion stops until the connection is restored.

Common Causes

Changed login credentials on the provider account
Provider account expired or deactivated
Revoked OAuth access (for OAuth-based providers)

How to Detect

Connection status: The connection’s status field changes to disconnected. You can check this via the API:

curl "https://api.withterminal.com/tsp/v1/connections/current" \
  -H "Authorization: Bearer your_secret_key" \
  -H "Connection-Token: con_tkn_your_token"

Webhooks: Subscribe to the connection.disconnected event for real-time notification. The webhook payload includes a reconnection link you can surface to the fleet. Dashboard: Disconnected connections are visible on the connections page with their current status.

How to Resolve

We recommend building workflows based on our supported webhooks to notify the fleet and invite them to reconnect.

Build an in-app or email based reconnection flow using the connection.disconnected webhook
Monitor for the connection.reconnected event to confirm restoration

For manual workflows the reconnection link is also accessible in the Terminal Dashboard. For more detail, see the Disconnected Connections guide.

Sync Failures

A sync failure occurs when Terminal encounters an error while attempting to fetch data from a provider. Unlike disconnects, the connection itself remains valid, but data may become temporarily stale.

Common Causes

Transient provider API errors or rate limiting
Temporary provider outages or degradation
Unexpected data format changes from the provider

How to Detect

Sync status: Monitor sync jobs via the API or the sync.failed webhook event.

# Check sync history for a connection
curl "https://api.withterminal.com/tsp/v1/syncs" \
  -H "Authorization: Bearer your_secret_key" \
  -H "Connection-Token: con_tkn_your_token"

Webhooks: Subscribe to sync.failed to detect failures in real-time.

How to Resolve

Most sync failures are transient and resolve automatically on the next sync cycle. Terminal’s ingestion pipeline includes built-in retry logic for common provider errors. If a failure persists across multiple sync cycles, Terminal’s engineering team will triage the issue to resolve. If you are seeing sync failures persist for multiple days, contact Terminal support for investigation.

Sync failures are triaged and addressed by the Terminal team. You do not typically need to take action beyond monitoring.You can always reach out to Terminal support for clarification or questions about ongoing sync failures

Issues

Issues are the most granular category of connection health. They represent problems encountered during data ingestion that don’t fully block the sync but may cause specific data to be incomplete or unavailable. Unlike disconnects and sync failures, issues affect only a subset of the data for a connection. For example, a connection may successfully sync vehicles, drivers, and trips but report an issue indicating that HOS logs are inaccessible due to missing permissions.

Issue Lifecycle

Each issue has a status that tracks its current state:

Status	Description
`ongoing`	The issue was observed during a recent sync and continues to affect data
`resolved`	The issue has not been observed recently and is considered resolved

Issues are automatically deduplicated. If the same issue is observed across multiple syncs, the existing issue is updated rather than creating duplicates. The firstReportedAt and lastReportedAt timestamps track the issue’s history. Issues automatically resolve when they are no longer observed during syncs.

Issue Codes

Each Issue’s error.code is its stable semantic identifier. Codes describe a shared diagnosis and remediation workflow rather than the provider or ingestion mechanism that discovered the condition. Provider-, capability-, and record-specific details remain in error.message. For example, oauth_scope_missing identifies the OAuth application update and fleet reauthentication workflow, while permission_missing identifies an ordinary provider permission change. The Issue also includes a resolutionType describing whether action is required, Terminal will retry automatically, Terminal owns the work, the condition is a known limitation, or investigation is required. When available, documentationUrl links to the dedicated resolution guide for that code.

Monitoring Issues

API

Use the List Issues endpoint to query issues for a connection. You can filter by status, Issue code, and date range.

# List all ongoing issues for a connection
curl "https://api.withterminal.com/tsp/v1/issues?connectionId=conn_xxx&status=ongoing" \
  -H "Authorization: Bearer your_secret_key"

# List issues with a specific code
curl "https://api.withterminal.com/tsp/v1/issues?connectionId=conn_xxx&errorCode=permission_missing" \
  -H "Authorization: Bearer your_secret_key"

Webhooks

Subscribe to issue webhook events for real-time monitoring:

issue.reported - Fired when a new issue is observed or a previously resolved issue recurs
issue.resolved - Fired when an ongoing issue is resolved

Dashboard

The Terminal dashboard provides a dedicated issues view for each connection on the Issues tab, showing Issue code, status, message, resolution guide, and reporting timestamps.

Resolving Issues Manually

You can manually mark an issue as resolved using the Resolve Issue endpoint. If the underlying problem still exists, the issue will be re-reported on the next sync.

curl --request POST \
  --url "https://api.withterminal.com/tsp/v1/issues/iss_xxx/resolve" \
  -H "Authorization: Bearer your_secret_key"

Recommended Monitoring Strategy

For production integrations, we recommend the following approach to connection health monitoring:

Subscribe to key webhooks: At minimum, subscribe to connection.disconnected, sync.failed, and issue.reported events to be notified of health changes in real-time.
Surface disconnects to fleets: Use the connection.disconnected webhook to trigger notifications to fleets with the reconnection link, either through your own product’s UI or by sending emails to fleets.
Monitor ongoing issues: Periodically query the Issues API for ongoing issues across your connections to identify persistent data quality problems that may need attention.
Track sync health: Use sync.completed and sync.failed webhooks to monitor the overall health of your data pipeline and detect providers experiencing degradation.

Data Replication - Sync vs replication and egress options
Syncing via the API - Pull patterns and modifiedAfter
Disconnected Connections - Handling disconnected connections
Issue Model - Full issue schema reference
Webhooks - Setting up and managing webhooks
List Issues API - Query issues via the API

Get Started

Development Lifecycle

Connect Your Customers

Working With Data

Managing Connections

Notifications

Resources

Connection Health Monitoring

Overview

Connection Disconnects

Common Causes

How to Detect

How to Resolve

Sync Failures

Common Causes

How to Detect

How to Resolve

Issues

Issue Lifecycle

Issue Codes

Monitoring Issues

API

Webhooks

Dashboard

Resolving Issues Manually

Recommended Monitoring Strategy

​Overview

​Connection Disconnects

​Common Causes

​How to Detect

​How to Resolve

​Sync Failures

​Common Causes

​How to Detect

​How to Resolve

​Issues

​Issue Lifecycle

​Issue Codes

​Monitoring Issues

​API

​Webhooks

​Dashboard

​Resolving Issues Manually

​Recommended Monitoring Strategy

​Related Resources

Overview

Connection Disconnects

Common Causes

How to Detect

How to Resolve

Sync Failures

Common Causes

How to Detect

How to Resolve

Issues

Issue Lifecycle

Issue Codes

Monitoring Issues

API

Webhooks

Dashboard

Resolving Issues Manually

Recommended Monitoring Strategy

Related Resources