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

# Syncs

> Monitor data ingestion runs across all connectors in your environment.

Syncs are the background runs that keep your knowledge stores current. You monitor them because stale data means wrong agent answers — if a sync fails silently, your agent keeps serving yesterday's content while the source has moved on. This page gives you environment-wide visibility into every ingestion run.

A sync is a single ingestion run for a data source. The syncs endpoints give you an environment-wide view of ingestion health: what ran, what succeeded, and what needs attention.

## Sync states

| State       | Meaning                                             |
| ----------- | --------------------------------------------------- |
| `pending`   | Queued, not yet started.                            |
| `running`   | Actively ingesting content.                         |
| `completed` | Finished successfully.                              |
| `failed`    | Encountered an error; inspect the sync for details. |

## List all syncs (environment-wide)

```bash theme={"dark"}
curl "https://api.hexelstudio.com/data/v1/syncs?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

### Response

<ResponseField name="items" type="array">
  Array of sync objects.
</ResponseField>

<ResponseField name="items[].id" type="string">
  Unique sync identifier.
</ResponseField>

<ResponseField name="items[].datasource_id" type="string">
  The data source this sync belongs to.
</ResponseField>

<ResponseField name="items[].state" type="string">
  One of `pending`, `running`, `completed`, `failed`.
</ResponseField>

<ResponseField name="items[].started_at" type="string">
  ISO 8601 timestamp when the sync started (null if pending).
</ResponseField>

<ResponseField name="items[].completed_at" type="string">
  ISO 8601 timestamp when the sync finished (null if not terminal).
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="page_size" type="integer">
  Items per page.
</ResponseField>

## List syncs for a data source

```bash theme={"dark"}
curl "https://api.hexelstudio.com/data/v1/datasources/YOUR_SOURCE_ID/syncs?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"
```

## Errors

| `code`                   | HTTP | When                                       |
| ------------------------ | ---- | ------------------------------------------ |
| `AUTH.PERMISSION_DENIED` | 403  | Missing `data-platform:connector:read`.    |
| `RESOURCE.NOT_FOUND`     | 404  | The data source or sync run doesn't exist. |

## Production recommendations

* Review the environment-wide sync view on a schedule so stale or failing sources don't go unnoticed.
* Set each source's sync cadence to match how often the underlying data changes.
* Treat repeated `failed` syncs as an alert; pause and reconfigure the source rather than letting it retry indefinitely.

## Rate limits

10,000 requests per organization per hour. Pagination: `page` >= 1, `page_size` 1–100 (default 20).

<Tip>
  Review the environment-wide syncs view regularly. A `completed` status confirms ingestion finished, but check item counts to verify completeness.
</Tip>

<AccordionGroup>
  <Accordion title="Handling failed syncs">
    When a sync fails, inspect the error details in the sync object. Common causes:

    * Bucket permissions changed (missing `s3:GetObject` / `s3:ListBucket`).
    * Objects exceed `max_object_size_mb`.
    * Unsupported file formats in the bucket.

    Fix the underlying issue, then trigger a new sync from the [Connectors](/docs/data-platform/connectors) endpoint.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Connectors" icon="plug" href="/docs/data-platform/connectors">
    Configure the sources that sync.
  </Card>

  <Card title="Knowledge Stores" icon="book" href="/docs/data-platform/knowledge-stores">
    Where synced content lands.
  </Card>

  <Card title="Documents & Uploads" icon="file-arrow-up" href="/docs/data-platform/documents">
    Add files directly.
  </Card>

  <Card title="Data Platform Overview" icon="database" href="/docs/data-platform/overview">
    The full data model.
  </Card>
</CardGroup>

## Next steps

Continue to [Context Bundles](/docs/data-platform/context-bundles).