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

# Sync Sessions

> Monitor and manage data synchronization

# Sync Sessions

Sync sessions (also called sync executions) represent individual data synchronization runs between Tether and your connected platforms. Monitor sync activity to ensure data stays current and identify issues.

## What is a Sync Session?

A sync session is a single execution of an integration's data synchronization:

* Tether connects to the external platform
* Data is fetched based on the integration's capabilities
* Individual records (sync items) are processed
* The session completes with a status and statistics

## Viewing Sync Sessions

### Accessing Sync History

<Steps>
  <Step title="Go to Integrations">
    Navigate to **Integrations** in the sidebar
  </Step>

  <Step title="Select Integration">
    Click on the integration you want to inspect
  </Step>

  <Step title="View Execution History">
    The integration detail page shows a table of past sync executions
  </Step>
</Steps>

### Sync Execution List

Each sync execution in the list displays:

| Column              | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **Status**          | Visual badge showing the execution result                                |
| **Domain Type**     | What type of data was synced (e.g., sales\_orders, warehouse\_inventory) |
| **Started At**      | When the sync execution began                                            |
| **Duration**        | How long the sync took (in seconds)                                      |
| **Records Fetched** | Number of records retrieved from the external system                     |
| **Statistics**      | Breakdown of success, failed, and skipped record counts                  |

## Sync Types

### Scheduled Sync

Syncs that run automatically based on the integration's cron schedule:

| Aspect       | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| **When**     | Based on the configured cron expression and timezone        |
| **What**     | Incremental data since last sync (new and modified records) |
| **Duration** | Varies based on data volume                                 |
| **Use**      | Regular ongoing synchronization                             |

### Manual Sync

User-triggered synchronization for immediate data fetch:

<Steps>
  <Step title="Go to Integration Detail">
    Navigate to the integration's detail page
  </Step>

  <Step title="Click Trigger Sync">
    Click the **Trigger Sync** button to start an immediate sync
  </Step>

  <Step title="Monitor Progress">
    The new execution will appear in the execution history
  </Step>
</Steps>

### Full Re-Sync

After resetting sync state (admin only), the next sync performs a full data fetch:

| Aspect       | Description                                     |
| ------------ | ----------------------------------------------- |
| **When**     | After an admin resets sync state                |
| **What**     | All available data from the external system     |
| **Duration** | Longer (full data volume)                       |
| **Use**      | Recovery, re-import after fixing mapping issues |

## Sync Execution Details

Click on a sync execution to see its detail page.

### Execution Summary

| Field               | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| **Status**          | Overall execution result                                            |
| **Dry Run**         | Whether this was a dry run (mapping validation only, no data saved) |
| **Duration**        | Total execution time in seconds                                     |
| **Records Fetched** | Total records retrieved from the external system                    |
| **Domain Type**     | The data type that was synced                                       |

### Statistics

Each execution tracks aggregate statistics:

| Statistic   | Description                                          |
| ----------- | ---------------------------------------------------- |
| **Success** | Records processed successfully                       |
| **Failed**  | Records that encountered errors                      |
| **Skipped** | Records that were skipped (e.g., already up to date) |

### Sync Items

The execution detail page shows a table of individual sync items — the records that were processed during the sync. Each item shows:

| Column            | Description                            |
| ----------------- | -------------------------------------- |
| **Sync Status**   | Status badge for the individual record |
| **Error Message** | Error details if the record failed     |
| **Fetched At**    | When the record was retrieved          |
| **Domain Type**   | Data type of the record                |
| **External ID**   | Identifier from the external system    |
| **Records**       | Record count (for aggregate items)     |

### Sync Item Statuses

Individual sync items can have the following statuses:

| Status            | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| **Processing**    | Record is currently being processed                             |
| **Success**       | Record was processed successfully                               |
| **Failed**        | Record encountered an error during processing                   |
| **Skipped**       | Record was skipped (e.g., no changes detected)                  |
| **Mapped**        | Record was successfully mapped to Tether entities               |
| **PartialMapped** | Record was partially mapped (some fields could not be resolved) |

### Filtering Sync Items

The sync items table supports filtering to help you investigate specific issues:

| Filter          | Description                                               |
| --------------- | --------------------------------------------------------- |
| **Status**      | Filter by sync item status (e.g., show only Failed items) |
| **Search**      | Text search across sync item fields                       |
| **Domain Type** | Filter by data type                                       |

## Error Analysis

### Unmapped SKU and Channel Errors

A common source of sync failures is unmapped SKUs or channels. The execution detail page provides aggregate error analysis:

* **Unique unmapped SKUs**: List of SKU identifiers from the external system that don't match any Tether SKU
* **Unique unmapped channels**: Channel identifiers that couldn't be resolved
* **Top errors**: Most frequently occurring error messages

This helps you quickly identify which mappings need to be configured before the data can sync successfully.

### Viewing Error Details

For aggregate sync items (items that represent batches of records), you can click to view the detailed error breakdown showing individual record errors within the batch.

## Monitoring Sync Health

### Key Indicators

| Indicator            | Healthy                         | Needs Attention                 |
| -------------------- | ------------------------------- | ------------------------------- |
| **Execution Status** | Consistently successful         | Repeated failures               |
| **Failed Count**     | 0 or very low                   | Increasing over time            |
| **Records Fetched**  | Consistent with expected volume | Sudden drop or zero             |
| **Duration**         | Within expected range           | Significantly longer than usual |

### Checking Sync Schedule

From the integration detail page, verify:

| Field         | Description                                  |
| ------------- | -------------------------------------------- |
| **Last Sync** | When the integration last executed           |
| **Next Sync** | When the next scheduled execution will occur |
| **Schedule**  | The cron expression and timezone             |

If the last sync is older than expected based on the schedule, the integration may be disabled or experiencing issues.

## Managing Sync Issues

### Retrying After Failures

<Steps>
  <Step title="Review Failed Execution">
    Click on the failed execution to see error details
  </Step>

  <Step title="Check Sync Items">
    Filter sync items by "Failed" status to identify specific issues
  </Step>

  <Step title="Fix Root Cause">
    Address the underlying problem (e.g., add missing SKU mappings, fix credentials)
  </Step>

  <Step title="Trigger Manual Sync">
    Go back to the integration detail page and click **Trigger Sync**
  </Step>
</Steps>

### Common Sync Issues

| Issue                     | Cause                                    | Solution                                        |
| ------------------------- | ---------------------------------------- | ----------------------------------------------- |
| **Unmapped SKUs**         | External SKU IDs don't match Tether SKUs | Configure SKU external ID mappings              |
| **Unmapped Channels**     | Channel identifiers not recognized       | Verify channel configuration                    |
| **Authentication Failed** | Expired or invalid credentials           | Update integration credentials                  |
| **No Records Fetched**    | Date range issue or empty data source    | Check integration configuration and source data |

## Dry Run Mode

When an integration runs in dry run mode, sync executions are marked with a **Dry Run** indicator. In dry run mode:

* Data is fetched and mapping is validated
* No data is actually saved to Tether
* You can review sync items to see what would be processed
* Useful for testing new integrations or debugging mapping issues

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor Regularly">
    Check sync status routinely:

    * Review execution history after schedule changes
    * Investigate any increase in failed records
    * Verify records fetched counts are reasonable
  </Accordion>

  <Accordion title="Investigate Errors Promptly">
    Don't let errors accumulate:

    * Check error details on failed executions
    * Resolve unmapped SKU/channel issues quickly
    * Use dry run mode to test fixes before enabling
  </Accordion>

  <Accordion title="Use Filtering">
    When investigating issues:

    * Filter sync items by "Failed" status to focus on errors
    * Search for specific external IDs
    * Filter by domain type to isolate data categories
  </Accordion>

  <Accordion title="Reset When Needed">
    If sync state becomes corrupted:

    * Ask an admin to reset sync state
    * This forces a full re-sync on the next execution
    * Monitor the full sync carefully for errors
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Integration Setup" icon="plug" href="/integrations/setup">
    Configure integrations
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/troubleshooting">
    Resolve sync issues
  </Card>

  <Card title="Channels" icon="shopping-cart" href="/channels/overview">
    Manage channels
  </Card>

  <Card title="Data Exports" icon="download" href="/tips/exports">
    Export data manually
  </Card>
</CardGroup>