> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Health Monitoring

> Understand the different categories of connection health events, how to monitor them, and what actions to take.

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](/guides/syncing-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.

| 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:

```bash theme={null}
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`](/api-reference/webhook-events/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`](/api-reference/webhook-events/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](/guides/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`](/api-reference/webhook-events/sync-failed) webhook event.

```bash theme={null}
# 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`](/api-reference/webhook-events/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](mailto:support@withterminal.com) for investigation.

<Note>
  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](mailto:support@withterminal.com) for clarification or questions about ongoing sync failures
</Note>

## Issues

[Issues](/models/issue) 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 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](/api-reference/issues/list-issues) endpoint to query issues for a connection. You can filter by status, issue type, and date range.

```bash theme={null}
# 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`](/api-reference/webhook-events/issue-reported) - Fired when a new issue is observed or a previously resolved issue recurs
* [`issue.resolved`](/api-reference/webhook-events/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](/api-reference/issues/resolve-issue) endpoint. If the underlying problem still exists, the issue will be re-reported on the next sync.

```bash theme={null}
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:

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.

## Related Resources

* [How to Sync Data](/guides/syncing-data) - Guide to syncing and replicating data
* [Disconnected Connections](/guides/disconnected-connections) - Handling disconnected connections
* [Issue Model](/models/issue) - Full issue schema reference
* [Webhooks](/terminal-platform/webhooks) - Setting up and managing webhooks
* [List Issues API](/api-reference/issues/list-issues) - Query issues via the API