# Check your connections' health

The **Connected** tab of Connections answers one question: is your data current, and does anything need you? Each connection shows its state in an icon and a word, and, when something is wrong, the one thing to do about it.

Only the owner and admins can see it (see [Connect a service](connect-a-service.md)).

## Open it

1. Open **Connections** (`g` then `c`) and choose **Connected**.
2. Or press the "… needs you" link under the Connections heading, or choose **Connections needing attention** in the command palette (`⌘K` / `Ctrl K`): both show only the connections that need you.

The tab starts with a summary line: "17 of 18 connections healthy", and "1 needs you" as a link. A switch above the list toggles between **All** and **Needs you** ("Showing the connections that need you."; **Show all** goes back).

The list puts the most urgent first, then by name. Each row has the **Service** and account, its **State**, what it **Feeds** (its projects, or "No project yet"), its **Last success**, **Next sync** and **First number**. While older history loads, a bar says "Backfilling … history". A connection whose account had nothing to read once its history loaded says so where the number would be: "Connected. Stripe shows no live charges in the account's history."

## The states

| State | It says | What to do |
|---|---|---|
| **Connecting** | "Checking access and fetching the first page of data." After a minute: "Taking longer than usual. We'll keep trying." | Nothing: "Nothing to do: it carries on by itself." |
| **Syncing** | "Syncing · backfilled to …": "Your last 30 days are in. Older history is loading; this can take a few minutes for large accounts." | Nothing: "Nothing to do. Dashboards are already usable." |
| **Healthy** | "Synced 6 minutes ago. Next sync in 9 minutes." With nothing at the service: "Connected. … shows no … in …." first. | Nothing. **Sync now** syncs it at once. |
| **Stale** | "Stale since …": "We haven't had new data from … since …." (or the service's own reason) | Press **Test again** (`t`). For Google Cloud billing, **Check the export in Billing** opens the billing export's page first. |
| **Needs you to sign in again** | "Needs you · sign in again · since …": "… stopped accepting ShipVitals' access on …. Your data up to then is still shown." When the key lost a permission: "Add **Subscriptions · Read** to the key." (or, when ShipVitals can't tell which: "The key is missing a permission ShipVitals needs. Add it to the key at …, or replace the key.") | Press **Reconnect …** (`r`). The connect dialog opens for that account: paste a new key or sign in again. |
| **Failing** | "Failing since …": "… returned errors 3 times in a row. We'll try again in 1 hour." After a day: "It has been failing for more than a day. Check whether … reports a problem on its status page." | Press **Test again** (`t`), or **See the errors** for the sync runs. After a day, **… status page** opens the service's status page, where it has one. |
| **Rate-limited** | "Paused by …'s rate limit · resumes …": "… asked us to slow down. Nothing is lost; we'll catch up after …." | Nothing: it carries on by itself. |
| **Partial** | "2 of 15 resources missing": "ShipVitals can't read …." | Give access to what's missing, then **Test again**. For Google Cloud, **Copy the fix** opens the wizard's Check access with just the missing lines (see [Connect Google Cloud](connect-google-cloud.md)). |
| **Revoked** | "Disconnected in … since …": "ShipVitals' access was removed in … on …. History up to then is kept." | Press **Connect … again** (`r`; **Install again** for an app you installed, such as GitHub), or **Remove this connection and its data**. |
| **Paused** | "Paused by … on …." | Press **Resume**. |
| **Paused**, over your plan | "Your plan includes 5 connections; this is the 6th. It starts syncing when you remove one or change plan." | Remove another connection, or press **See plans**. |
| **Paused**, disconnected | "Disconnected, with the data it brought in kept. Add its key again to reconnect it." | Press **Reconnect …** and paste its key. |

Connections that need you also show in the bell ("… needs you to sign in again", "… was disconnected at the provider", "… keeps failing to sync") and as **Needs you** cards in **Suggested**.

## Sync now

- One connection: select its row and press `t`, or open it and press **Sync now** (**Test again** when it's stale or failing). The toast says "… syncs now.", then "… synced: Healthy." when the run finishes (or "… is still syncing. Its state updates here when it finishes.").
- Several: tick their boxes (or `x`) and press **Sync now** in the bar. The toast says "3 connections sync now." Those that are paused, removed at their provider, or synced in the last 5 minutes are skipped, and the toast says so.

A connection synced in the last 5 minutes says "… synced in the last 5 minutes. Try again in a few minutes."

## Open a connection

Press a row's name, or `Enter` on the row. A panel opens over the list (the whole screen on a phone):

- **What's happening**: the state, its explanation and its action.
- **Actions**: **Replace key** (**Reconnect …** for a service you signed in to or installed, which has no key), **Sync now**, **Pause** and **Disconnect**.
- What it feeds, its first number, and **The access it has**.
- **Credential**: the key's last characters only ("Key …"), "Added by … on …", "Last used …", how often it was used ("Used 96 times in the last 24 hours, all by scheduled sync."), and **Recent decryptions**: the latest 20, each with what it was for and when ("Decrypted by scheduled sync · 10:15").
- **What we store**: what is kept and how, with **Revoke it in …**, a link to the service's own page for taking ShipVitals' access away.
- **Sync runs**: the last 20, each **Running**, **Succeeded** or **Failed**. **Show older runs** adds 20 more at a time.

`Esc` closes it, and the cursor goes back to the row.

### Replace the key

Press **Replace key** (or `r`; when the state needs it, or for a service you signed in to or installed, the button is **Reconnect …**). The connect dialog opens for this account. Paste the new key and press **Test connection**, then **Done**. The connection keeps its history. A key for another account offers **Add it as a new connection** instead (see [Connect a service](connect-a-service.md#already-connected)).

### Pause and resume

Press **Pause**. It stops syncing at once. The toast says "… is paused." with **Undo** for 10 seconds. Later, open it and press **Resume**: "… resumes syncing."

### Disconnect

1. Press **Disconnect**. The panel asks **Disconnect …?**: "ShipVitals deletes the key at once. What should happen to the data it brought in?"
2. Press **Disconnect, keep the data** or **Disconnect and delete the data** (or **Cancel**).
3. The toast says "… is disconnected. Its data is kept." or "… is disconnected. Its data is being deleted.", then what happened to its access at the provider:
   - for a key you pasted, "Delete its key in … too." ShipVitals can't revoke a pasted key: the panel says so and links **Revoke it in …**;
   - for a service you signed in to or installed, "Its access at … is revoked.", or "Its access at … stays for your other connection to it." when another connection still uses it. If the provider refused, "ShipVitals couldn't revoke its access at …: remove ShipVitals there."

The key is deleted either way. A connection disconnected with its data kept stays in the list as Paused until you add its key again.

## When it doesn't work

| The page says | What to do |
|---|---|
| "This connection doesn't exist, or it was removed." | Someone disconnected it. Close the panel. |
| "Your plan has no room for another connection. Remove one, or see plans." | **Resume** needs a free place in your plan. |
| "This connection was disconnected. Add its key again to reconnect it." | Press **Reconnect …** and paste its key. |
| "This connection was removed at the provider. Connect it again to resume." | Press **Connect … again**. |
| "… isn't syncing, so there's nothing to run." | It's paused or revoked; resume or reconnect it first. |
| "That didn't go through. Try again." | Check your connection and try again. |

## Keyboard

| Key | Does |
|---|---|
| `j` `k` (or `↓` `↑`) | Move between connections |
| `x` | Select the connection |
| `Enter` | Open it |
| `r` | Reconnect, or replace its key |
| `t` | Test again (sync now) |
| `Esc` | Close the panel |

`r` and `t` also work in the open panel. Single keys follow **Single-key shortcuts** in [Account settings](account-settings.md).
