> ## 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 [Data Replication](/guides/data-replication) and the [API sync guide](/guides/syncing-via-the-api), 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:

```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 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](/api-reference/issues/list-issues) endpoint to query issues for a connection. You can filter by status, Issue code, 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 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`](/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 code, status, message, resolution guide, 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

* [Data Replication](/guides/data-replication) - Sync vs replication and egress options
* [Syncing via the API](/guides/syncing-via-the-api) - Pull patterns and `modifiedAfter`
* [Disconnected Connections](/guides/disconnected-connections) - Handling disconnected connections
* [Issue Model](/models/issue) - Full issue schema reference
* [Webhooks](/guides/webhooks) - Setting up and managing webhooks
* [List Issues API](/api-reference/issues/list-issues) - Query issues via the API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.