sync

Sync To Cloud

Sync local data to Cognee Cloud.

This endpoint triggers synchronization of local Cognee data to your cloud instance. It uploads your local datasets, knowledge graphs, and processed data to the cloud for backup, sharing, or cloud-based processing.

Request Body (JSON)

{
    "dataset_ids": ["123e4567-e89b-12d3-a456-426614174000", "456e7890-e12b-34c5-d678-901234567000"]
}

Response

Returns immediate response for the sync operation:

run_id: Unique identifier for tracking the background sync operation
status: Always “started” (operation runs in background)
dataset_ids: List of dataset IDs being synced
dataset_names: List of dataset names being synced
message: Description of the background operation
timestamp: When the sync was initiated
user_id: User who initiated the sync

Cloud Sync Features

Automatic Authentication: Uses your Cognee Cloud credentials
Data Compression: Optimizes transfer size for faster uploads
Smart Sync: Automatically handles data updates efficiently
Progress Tracking: Monitor sync status with sync_id
Error Recovery: Automatic retry for failed transfers
Data Validation: Ensures data integrity during transfer

Example Usage

# Sync multiple datasets to cloud by IDs (JSON request)
curl -X POST "http://localhost:8000/api/v1/sync" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your-token" \
  -d '{"dataset_ids": ["123e4567-e89b-12d3-a456-426614174000", "456e7890-e12b-34c5-d678-901234567000"]}'

# Sync all user datasets (empty request body or null dataset_ids)
curl -X POST "http://localhost:8000/api/v1/sync" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your-token" \
  -d '{}'

Error Codes

400 Bad Request: Invalid dataset_ids format
401 Unauthorized: Invalid or missing authentication
403 Forbidden: User doesn’t have permission to access dataset
404 Not Found: Dataset not found
409 Conflict: Sync operation conflict or cloud service unavailable
413 Payload Too Large: Dataset too large for current cloud plan
429 Too Many Requests: Rate limit exceeded

Notes

Sync operations run in the background - you get an immediate response
Use the returned run_id to track progress (status API coming soon)
Large datasets are automatically chunked for efficient transfer
Cloud storage usage counts against your plan limits
The sync will continue even if you close your connection

POST

api

sync

Sync To Cloud

curl --request POST \
  --url https://api.cognee.ai/api/v1/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "datasetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for sync operations.

datasetIds

string<uuid>[] | null

Response

Successful Response

{key}

SyncResponse · object

Response model for sync operations.

Show child attributes

Get Sync Status OverviewCheck if there are any running sync operations for the current user. This endpoint provides a simple check to see if the user has any active sync operations without needing to know specific run IDs. ## Response Returns a simple status overview: - **has_running_sync**: Boolean indicating if there are any running syncs - **running_sync_count**: Number of currently running sync operations - **latest_running_sync** (optional): Information about the most recent running sync if any exists ## Example Usage ```bash curl -X GET "http://localhost:8000/api/v1/sync/status" \ -H "Cookie: auth_token=your-token" ``` ## Example Responses **No running syncs:** ```json { "has_running_sync": false, "running_sync_count": 0 } ``` **With running sync:** ```json { "has_running_sync": true, "running_sync_count": 1, "latest_running_sync": { "run_id": "12345678-1234-5678-9012-123456789012", "dataset_name": "My Dataset", "progress_percentage": 45, "created_at": "2025-01-01T00:00:00Z" } } ```

⌘I

Sync To Cloud

curl --request POST \
  --url https://api.cognee.ai/api/v1/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "datasetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

{}