> ## 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'
      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: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SyncJobStatus:
      type: string
      enum:
        - running
        - completed
        - failed
        - interrupted
      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
        phase:
          anyOf:
            - type: string
            - type: 'null'
          title: Phase
          description: >-
            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:
          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
        started_at:
          type: string
          format: date-time
          title: Started At
          description: Timestamp when the job started.
        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.
        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: Derived percent complete when total_files is known.
        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:** PENDING → RUNNING → COMPLETED/FAILED

        **Tracked Metrics:**
        - files_synced: Successfully created objects
        - files_failed: Objects sent to Dead Letter Queue
        - started_at/completed_at: Timing for duration calculation
    PaginationResponse:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        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
        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.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  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 header returns
        403; an invalid or revoked key returns 401.
    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`.

````