Skip to main content
POST
/
v1
/
buckets
/
{bucket_id}
/
syncs
/
list
List Sync Configurations
curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_id}/syncs/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "description": "List all configurations (no filters)"
}'
{
  "description": "Empty result set",
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "results": [],
  "total": 0
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
bucket_id
string
required

Query Parameters

​
limit
integer | null
​
offset
integer | null

Body

application/json

Request to filter sync configurations for listing.

All filters are optional - when omitted, returns all sync configurations for the bucket. Multiple filters can be combined for precise queries.

Use Cases: - Find all syncs for a specific connection - List only active or paused syncs - Filter by status to find failed syncs

Requirements: - All fields are OPTIONAL - Multiple filters are combined with AND logic - Empty request returns all configurations

​
connection_id
string | null

Filter sync configurations by connection ID. NOT REQUIRED. When provided, only returns syncs using this connection. Useful for managing syncs across multiple storage providers. Example: 'conn_abc123'

Examples:

"conn_abc123"

"conn_s3_prod"

​
status
enum<string> | null

Filter sync configurations by status. NOT REQUIRED. Valid values: 'pending', 'processing', 'completed', 'failed', 'paused'. Useful for finding syncs that need attention or monitoring. Example: 'failed' to find syncs with errors. Enumeration of task statuses for tracking asynchronous operations.

Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution.

Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces)

Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted

ACTIVE: Entity is active and operational (for buckets, collections, etc.)
ARCHIVED: Entity has been archived
SUSPENDED: Entity has been temporarily suspended

Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately.

Polling Guidance: - Poll tasks in PENDING, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

Available options:
PENDING,
IN_PROGRESS,
PROCESSING,
COMPLETED,
COMPLETED_WITH_ERRORS,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
Examples:

"pending"

"processing"

"failed"

​
is_active
boolean | null

Filter sync configurations by active status. NOT REQUIRED. True: Only active syncs that are currently monitoring/processing. False: Only paused/disabled syncs. Omit to include both active and inactive.

Examples:

true

false

Response

Successful Response

Response containing a list of sync configurations with pagination.

Wraps the list of sync configurations with pagination metadata to support efficient browsing of large result sets.

Response Structure: - results: The actual sync configuration objects - pagination: Links and metadata for navigation - total: Total count for client-side progress indicators

​
results
SyncConfigurationModel · object[]
required

List of sync configurations matching the query filters. ALWAYS PRESENT. May be empty if no configurations match. Each item is a complete SyncConfigurationModel. Ordered by creation date (newest first).

​
pagination
object
required

Pagination metadata for navigating result sets. ALWAYS PRESENT. Contains next/previous links, current page info. Use the provided links for cursor-based pagination.

​
total
integer
required

Total number of sync configurations matching the filters. ALWAYS PRESENT. Useful for progress indicators and UI display. Note: This is the total across all pages, not just current page.

Examples:

0

5

42