> For the complete documentation index, see [llms.txt](https://docs.kula.digital/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kula.digital/your-data-sources/operating.md).

# Keeping your connectors healthy

Every connector is set up differently, but they all **run the same way**. So this one page covers operating *all* of them: how to spot a gap, what happens when a provider has a bad day, how to recover, and the one-minute weekly check that keeps everything flowing.

## How a connector keeps itself current

After your first import, each connector tops itself up on a schedule — you don't re-import by hand. Two things make this safe to leave running:

* **Re-running never harms your data.** Imports only **fill gaps**. They never overwrite richer data you already have with something thinner, and the same record is never stored twice.
* **It moves forward only on success.** A connector advances its place in your history *only* when a pull fully succeeds. If a pull half-fails, it simply tries that bit again next time — it doesn't skip ahead and leave a hole.

## Spotting a gap

A **gap** is a stretch of time where data should exist but doesn't — a month with zero attendances at a studio that was open is a gap, not a quiet month. Gaps usually come from the source, not from Kula: a provider was down, a key expired for a while, or a manual export missed some rows.

You'll notice a gap one of three ways:

* The AI tells you. When you ask a question it can't fully answer, it says so and points at the missing period — it won't invent a number.
* The diagnostic flags it. [Running the diagnostic](/get-started/first-diagnostic.md) counts your activity month by month and marks any suspicious gaps.
* The connector page shows it. Each connector has a **Data coverage** card (below) that draws every day and outlines any with no data.

## Data coverage, day by day

Open any connector and you'll see a **Data coverage** card: a calendar-style grid with one small square per day, one row of squares per kind of data (classes, attendance, sales, and so on). A square is green when that day has data — darker the busier the day — and outlined in coral when a day that should have data has none. Each stream shows a running count ("312 of 365 days") and a **No gaps** / **N days missing** badge, so you can see at a glance whether anything's missing and exactly when.

The grid charts the **real event dates** — the actual class dates and sale dates from your tidy data, not when we imported them — so a missing day is a genuinely missing day, not an artefact of when the import ran. (Coverage appears once you've run **Process**, because it reads the tidy tables.)

For each missing range the card gives you two buttons:

* **Re-pull** — dispatches a fresh, forced pull over *just that window*. It's idempotent and only fills the hole, so it's always safe to click; the rest of your history is untouched. (CSV-style sources like ClassPass have no live source to re-pull from — there you re-import the export covering the window instead.)
* **Mark expected** — for a day that was legitimately quiet (you were closed for a public holiday, the studio hadn't opened yet). This tells Kula the empty day is correct, so it stops counting as missing and the AI knows not to read anything into it. You can mark a one-off date or a range, and tick **recurs every year** for things like Christmas. Marked days show as neutral grey, and you can un-mark one any time.

**To fill a gap:** click **Re-pull** on the missing range (or, for a CSV source, re-import the export covering it). Because pulls only fill gaps, this is always safe — it tops up what's missing and leaves the rest alone. If the day was genuinely quiet, **mark it expected** instead.

> **Behind the scenes.** A re-pull refreshes the raw import *and* re-runs Process over that window, so coverage actually moves — you don't need to click Process again afterwards. A nightly sweep also tops every connector up and re-processes, so most gaps close on their own overnight.

## When a provider has a bad day

Providers (Stripe, Wix, Mindbody, and the rest) occasionally rate-limit us, time out, or go down. Kula is built to ride this out:

* **Temporary hiccups** (the provider is busy or briefly down) are **retried automatically**, backing off and trying again. You usually won't even notice.
* **A genuinely stuck pull** is set aside safely and picked up on the next scheduled run, rather than being lost.
* **If something keeps failing**, the connector flags itself as needing attention and we email you — we don't fail silently.

The most common reason a connector gets stuck is an **expired or revoked key** at the provider's end (someone rotated a Stripe key, a Mindbody password changed, a Meta token lapsed). That shows up as a connection error.

## Recovering a connector

When a connector shows an error, recovery is almost always one of three moves:

1. **Reconnect (most common).** If the key or sign-in expired, generate a fresh one at the provider and re-enter it on the connector's page. See that source's page for exactly where its key lives — for example [Stripe](/your-data-sources/stripe.md), [Wix](/your-data-sources/wix.md), [Mindbody](/your-data-sources/mindbody.md).
2. **Re-pull the affected window.** Use the **Re-pull** button on the missing range in the **Data coverage** card to force a fresh pull over just that period. Safe to repeat — it only fills gaps.
3. **Re-process.** If the import is fine but the tidy data looks off, click **Process** again. Re-processing is idempotent: it fixes what's pending and leaves the rest.

You won't lose anything by trying these in order. None of them overwrite good data.

## Your weekly glance

Once a week, open the **Connectors** page on your dashboard and check each source is green. That's it. If one needs attention, the page tells you what — usually "reconnect" — and the three moves above sort it out.

You can also ask the AI directly:

> *"Are any of my data connectors having problems, and what should I do about it?"*

It can read the recent error summary and tell you in plain English which source needs a look and why.

## The short version

* The **Data coverage** card draws every day and flags gaps; **Re-pull** fills a missing window, **Mark expected** clears a day that was legitimately quiet.
* Gaps come from the source, and a nightly sweep closes most of them on its own.
* Outages are retried for you; persistent ones get flagged and emailed.
* Recovery is almost always **reconnect**, then **re-pull**, then **re-process** — in that order, all safe to repeat.
* A weekly glance at the Connectors page is enough to stay ahead of it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kula.digital/your-data-sources/operating.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.