Skip to main content
GET
Get Sync Job

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace
string
header
required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

bucket_id
string
required
sync_config_id
string
required
sync_job_id
string
required

Response

Successful Response

Execution record for a single storage sync run.

Created when a sync is triggered (manually or by scheduler). Tracks progress, metrics, and errors for the sync execution.

Job Lifecycle: records are BORN status=RUNNING (pre-dispatch, before the lock attempt) → COMPLETED/FAILED/INTERRUPTED. started_at=None marks the born-but-not-yet-executing window; there is no PENDING status.

Tracked Metrics:

  • files_synced: Successfully created objects
  • files_failed: Objects sent to Dead Letter Queue
  • started_at/completed_at: Timing for duration calculation. started_at is the CURRENT ATTEMPT's execution start, stamped at the RUNNING transition (mark_sync_job_running) — None while queued. The document's provider-level created_at is record creation, so created_at→started_at is record-creation-to-execution-start (dispatch
    • admission + pre-RUNNING setup), NOT queue time alone. Rows written before this stamping existed (no metadata.started_at_source) carry a construction time here; their execution duration is unknown, not measured.
sync_config_id
string
required

Identifier of the sync configuration that spawned this job.

internal_id
string
required

Organization scope identifier.

namespace_id
string
required

Namespace scope identifier.

sync_job_id
string

Unique identifier for the sync job.

status
enum<string>
default:running

Current status of the sync job.

Available options:
running,
completed,
failed,
interrupted,
skipped
trigger
enum<string> | null

What started this job: scheduled (the polling loop), manual (a person, through the trigger endpoint), or resume (continuation of a sliced run). None on records written before this field shipped, which means 'not recorded' and NOT 'unknown trigger' — those jobs carry the free-form metadata.triggered_by string instead.

Available options:
scheduled,
manual,
resume
phase
string | null

Human-readable phase within a RUNNING job for observability (e.g. 'discovering', 'downloading', 'verifying', 're-verifying', 'idle'). Optional and descriptive — distinct from status, which is the coarse lifecycle state. Lets a sync that is re-verifying already-synced files (low net-new throughput, low percent) read as healthy rather than stuck. Back-compatible: older jobs have None.

total_files
integer | null

Total files expected for this sync run.

Required range: x >= 0
files_synced
integer
default:0

Number of files synced successfully in this job.

Required range: x >= 0
files_failed
integer
default:0

Number of files that failed to sync in this job.

Required range: x >= 0
files_verified
integer | null

OPTIONAL. Files the run re-checked and found already present, as opposed to newly transferred. A re-scan of a settled source is mostly this, so a run with files_synced=0 and files_verified>0 did work and found nothing new, which is a different state from a run that did nothing.

Required range: x >= 0
started_at
string<date-time> | null

Execution start of the CURRENT attempt, stamped at the RUNNING transition. None = not yet started (queued/pre-dispatch). Legacy rows (no metadata.started_at_source) hold a record-construction time instead — not execution evidence.

completed_at
string<date-time> | null

Timestamp when the job completed.

updated_at
string<date-time> | null

Last progress update timestamp for this job.

error
string | null

Last error encountered during the job.

Maximum string length: 1000
resumed_via
string | null

Set when this job record was reopened and re-run after its worker died without finalizing (value 'acks_late_redelivery': the broker redelivered the original message against the reaped record). On rows that predate per-attempt history (metadata.prior_attempts), this is the only retry signal; its absence proves nothing about whether a job retried.

metadata
Metadata · object

Optional metadata captured during execution (provider stats, cursors, etc.).

progress_percent
number | null

Derived percent complete when total_files is known.

Required range: 0 <= x <= 100
throughput_files_per_min
number | null

Derived successful-file throughput for the job.

Required range: x >= 0
lag_seconds
integer | null

Seconds since the latest progress update for running jobs.

Required range: x >= 0
current_cursor
string | null

Latest provider cursor/page token captured for this job.

progress
Progress · object

Derived progress summary for API observability.