Skip to main content
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 the How to Sync Data guide, which focuses on the happy-path for data ingestion.

​
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.
CategoryData ImpactAction RequiredHow It Surfaces
DisconnectsAll data ingestion stopsFleet must reconnectConnection status, webhooks, email notifications
Sync failuresData temporarily staleHandled by TerminalSync status, webhooks
Ingestion issuesSpecific data may be incompleteVariesIssues 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:
StatusDescription
ongoingThe issue was observed during a recent sync and continues to affect data
resolvedThe 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 Types

Terminal categorizes ingestion issues into the following types:

​
Missing Permissions

The credentials used for a connection are missing the permissions or OAuth scopes necessary to access certain data. Example: A Motive application is missing the hos_logs.logs scope, so HOS logs cannot be ingested. Resolution: The fleet or application owner needs to update the permissions on their provider account or OAuth application and reconnect.

​
Exceeded Retention Window

A sync requested data beyond the provider’s maximum retention period. The provider only stores a limited history, and the requested time range exceeds that limit. Example: Verizon Reveal enforces an account-specific data plan retention window. Requesting data with a start date earlier than the allowed retention date (for example, older than your plan’s configured history) will raise this issue. Resolution: This is informational. Adjust your sync’s time range to fall within the provider’s retention window, or accept that older data is unavailable from the provider.

​
Invalid Source ID

A source identifier from the provider contains characters or formatting that is incompatible with the provider’s own API, preventing Terminal from querying data for that specific resource. Example: A vehicle number in Verizon Reveal contains special characters that the Verizon API cannot process. Resolution: The fleet should correct the identifier in their provider account.

​
Unknown Device Type

For providers that return mixed asset types in a single data stream (e.g., vehicles, trailers, and other equipment), Terminal encountered an asset type it does not recognize as a vehicle or trailer. Example: In Geotab, the assets stream may include non-vehicle and non-trailer assets that Terminal skips during ingestion. Resolution: This is informational. Terminal skips unrecognized asset types to avoid ingesting incorrect data. If you believe an asset is being incorrectly skipped, contact support.

​
Missing Safety Configuration

A safety event rule or configuration is disabled or missing in the provider’s system, preventing Terminal from ingesting related safety data. Example: An exception event rule in Geotab has been disabled, so related exception events cannot be ingested. Resolution: The fleet should re-enable the safety rule in their provider account if the data is needed.

​
Inaccessible Data

Terminal was unable to fetch a specific piece of data due to a provider error or missing prerequisite data at extraction time. Example: Verizon Reveal driver safety may return a provider System Error - Please contact Fleetmatics Support. for a specific driver/day, causing Terminal to skip that time range as inaccessible data. Resolution: This may resolve on its own if the underlying provider issue is transient. If the issue persists, the data may not be recoverable without support from the provider.

​
Monitoring Issues

​
API

Use the List Issues endpoint to query issues for a connection. You can filter by status, issue type, 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 of a specific type
curl "https://api.withterminal.com/tsp/v1/issues?connectionId=conn_xxx&errorCode=missing_permissions" \
  -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 type, status, message, 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"
For production integrations, we recommend the following approach to connection health monitoring:
  1. 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.
  2. 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.
  3. Monitor ongoing issues: Periodically query the Issues API for ongoing issues across your connections to identify persistent data quality problems that may need attention.
  4. Track sync health: Use sync.completed and sync.failed webhooks to monitor the overall health of your data pipeline and detect providers experiencing degradation.