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

# List Sync Jobs

> List sync job history for a sync configuration.

Returns paginated job records ordered by most recent first.
Each job includes status, file counts, timing, and error details.
Use the optional status filter to find failed or running jobs.



## OpenAPI

````yaml post /v1/buckets/{bucket_id}/syncs/{sync_config_id}/jobs
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security:
  - BearerAuth: []
paths:
  /v1/buckets/{bucket_id}/syncs/{sync_config_id}/jobs:
    post:
      tags:
        - Bucket Syncs
      summary: List Sync Jobs
      description: |-
        List sync job history for a sync configuration.

        Returns paginated job records ordered by most recent first.
        Each job includes status, file counts, timing, and error details.
        Use the optional status filter to find failed or running jobs.
      operationId: list_sync_jobs_v1_buckets__bucket_id__syncs__sync_config_id__jobs_post
      parameters:
        - name: bucket_id
          in: path
          required: true
          schema:
            type: string
            title: Bucket Id
        - name: sync_config_id
          in: path
          required: true
          schema:
            type: string
            title: Sync Config Id
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Limit
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Page Size
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 10000
                minimum: 0
              - type: 'null'
            title: Offset
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Page
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: next_cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Next Cursor
        - name: after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: After
        - name: include_total
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Total
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListSyncJobsRequest'
        description: >-
          Keys this body does not declare are refused with 422 extra_forbidden
          naming the accepted keys (since 2026-11-02).
        x-unknown-keys:
          until: '2026-11-02'
          then: 422 extra_forbidden
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncJobListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
          NamespaceHeader: []
components:
  schemas:
    ListSyncJobsRequest:
      properties:
        status:
          anyOf:
            - $ref: '#/components/schemas/SyncJobStatus'
            - type: 'null'
          description: Filter jobs by status (running, completed, failed).
      type: object
      title: ListSyncJobsRequest
      description: Request to list sync job history for a sync configuration.
    SyncJobListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/SyncJobModel'
          type: array
          title: Results
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        total:
          type: integer
          title: Total
      type: object
      required:
        - results
        - pagination
        - total
      title: SyncJobListResponse
      description: Paginated list of sync jobs.
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    SyncJobStatus:
      type: string
      enum:
        - running
        - completed
        - failed
        - interrupted
        - skipped
      title: SyncJobStatus
      description: Lifecycle states for individual storage sync jobs.
    SyncJobModel:
      properties:
        sync_job_id:
          type: string
          title: Sync Job Id
          description: Unique identifier for the sync job.
        sync_config_id:
          type: string
          title: Sync Config Id
          description: Identifier of the sync configuration that spawned this job.
        internal_id:
          type: string
          title: Internal Id
          description: Organization scope identifier.
        namespace_id:
          type: string
          title: Namespace Id
          description: Namespace scope identifier.
        status:
          $ref: '#/components/schemas/SyncJobStatus'
          description: Current status of the sync job.
          default: running
        trigger:
          anyOf:
            - $ref: '#/components/schemas/SyncJobTrigger'
            - type: 'null'
          description: >-
            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.
        phase:
          anyOf:
            - type: string
            - type: 'null'
          title: Phase
          description: >-
            Human-readable phase within a RUNNING job for observability (e.g.
            'queued' until a worker starts the job, then '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:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Total Files
          description: Total files expected for this sync run.
        files_synced:
          type: integer
          minimum: 0
          title: Files Synced
          description: Number of files synced successfully in this job.
          default: 0
        files_failed:
          type: integer
          minimum: 0
          title: Files Failed
          description: Number of files that failed to sync in this job.
          default: 0
        files_verified:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Files Verified
          description: >-
            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.
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: >-
            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:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: Timestamp when the job completed.
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Last progress update timestamp for this job.
        error:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Error
          description: Last error encountered during the job.
        resumed_via:
          anyOf:
            - type: string
            - type: 'null'
          title: Resumed Via
          description: >-
            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:
          additionalProperties: true
          type: object
          title: Metadata
          description: >-
            Optional metadata captured during execution (provider stats,
            cursors, etc.).
        progress_percent:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Progress Percent
          description: >-
            Percent complete: files with an outcome (synced, failed,
            re-verified, unchanged or quarantined) / total_files when the total
            is known (total_files, or metadata.total_files_discovered on rows
            written before total_files was stored); otherwise 100 for a
            completed or skipped run and 0 for a run that has counted no file
            yet. Null only for a row with files counted and no total, which no
            current writer produces: every count write carries the total.
        throughput_files_per_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Throughput Files Per Min
          description: Derived successful-file throughput for the job.
        lag_seconds:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Lag Seconds
          description: Seconds since the latest progress update for running jobs.
        current_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Cursor
          description: Latest provider cursor/page token captured for this job.
        progress:
          additionalProperties: true
          type: object
          title: Progress
          description: Derived progress summary for API observability.
      type: object
      required:
        - sync_config_id
        - internal_id
        - namespace_id
      title: SyncJobModel
      description: |-
        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.
    PaginationResponse:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: >-
            Number of items matching the request across all pages, filters
            included. null unless the request set include_total=true (in the
            body or as ?include_total=true). A counted request that matches
            nothing returns 0.
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        page_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Size
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
          description: Number of pages at page_size. null unless include_total=true.
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
        previous_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Page
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      title: PaginationResponse
      description: |-
        PaginationResponse.

        Cursor-based pagination response:
        - Use next_cursor for navigation
        - Total count fields only populated when include_total=true
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.
    SyncJobTrigger:
      type: string
      enum:
        - scheduled
        - manual
        - resume
      title: SyncJobTrigger
      description: >-
        What started a sync job.


        The job record already carried this as a free-form
        ``metadata.triggered_by``

        string, which is fine for a log line and unusable as a query: a caller

        asking "has this sync completed a SCHEDULED run since the user connected
        it"

        had to match on prose. Those strings STAY, because

        ``reap_stale_running_jobs`` matches on ``triggered_by ==
        "queued_full_sync"``

        to restore ``pending_full_sync``; this enum is additive beside them.


        THERE IS DELIBERATELY NO ``api`` MEMBER. The trigger endpoint reads

        ``request.state.auth.user.user_id`` unconditionally, so a key-only
        caller is

        not distinguishable from a person there, and a member nothing can emit
        is a

        dead field that reads as a real one. Add it when the endpoint can tell
        the

        two apart.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        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, malformed,
        unknown, revoked, inactive or expired key returns 401; a key without the
        permission, scope or plan an operation needs returns 403.
    NamespaceHeader:
      type: apiKey
      in: header
      name: X-Namespace
      description: >-
        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`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.