> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-feat-openapi-i18n.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 페이지네이션 및 필터링으로 작업 목록 조회

> 인증된 사용자의 작업 목록을 페이지네이션으로 조회합니다.
목록 보기에 최적화된 경량 작업 데이터를 반환합니다.
페이로드 크기 감소를 위해 워크플로 및 전체 출력은 제외됩니다.




## OpenAPI

````yaml /openapi/cloud.ko.yaml get /api/jobs
openapi: 3.0.3
info:
  title: Comfy Cloud API
  description: >
    <Warning>

    **실험적 API:** 이 API는 실험적이며 변경될 수 있습니다. 

    엔드포인트, 요청/응답 형식 및 동작은 사전 통지 없이 수정될 수 있습니다.

    </Warning>


    Comfy Cloud용 API - 클라우드 인프라에서 ComfyUI 워크플로를 실행합니다.


    이 API를 사용하여 Comfy Cloud와 프로그래밍 방식으로 상호작용할 수 있습니다:

    - 워크플로 제출 및 관리

    - 파일 업로드 및 다운로드

    - 작업 상태 및 진행 상황 모니터링


    ## Cloud vs OSS ComfyUI 호환성


    Comfy Cloud는 최대 호환성을 위해 OSS ComfyUI와 동일한 API 인터페이스를 구현하지만,

    일부 필드는 호환성을 위해 허용되지만 다르게 처리되거나 무시됩니다:


    | 필드 | 엔드포인트 | Cloud 동작 |

    |-------|-----------|----------------|

    | `subfolder` | `/api/view`, `/api/upload/*` | **무시됨** - Cloud는 콘텐츠 주소 지정
    저장소(해시 기반)를 사용합니다. 클라이언트 측 구성을 위해 응답에 반환됩니다. |

    | `type` (input/output/temp) | `/api/view`, `/api/upload/*` | 부분적으로 사용됨 - 모든
    파일은 디렉토리 구조 대신 태그 기반 조직으로 저장됩니다. |

    | `overwrite` | `/api/upload/*` | **무시됨** - 콘텐츠 주소 지정 저장소는 동일한 콘텐츠가 항상 동일한
    해시를 갖도록 합니다. |

    | `number`, `front` | `/api/prompt` | **무시됨** - Cloud는 사용자별로 자체 공정 실행 대기열
    스케줄링을 사용합니다. |

    | `split`, `full_info` | `/api/userdata` | **무시됨** - Cloud는 항상 전체 파일 메타데이터를
    반환합니다. |


    이러한 필드는 기존 ComfyUI 클라이언트 및 워크플로와의 드롭인 호환성을 위해 API 스키마에 유지됩니다.
  version: 1.0.0
  license:
    name: GNU General Public License v3.0
    url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
servers:
  - url: https://cloud.comfy.org
    description: Comfy Cloud API
security:
  - ApiKeyAuth: []
tags:
  - name: workflow
    description: |
      워크플로를 제출하여 실행하고, 실행 대기열을 관리합니다.
      클라우드에서 ComfyUI 워크플로를 실행하는 주요 방법입니다.
  - name: job
    description: |
      작업 상태를 모니터링하고, 실행 기록을 확인하며, 실행 중인 작업을 관리합니다.
      작업은 POST /api/prompt를 통해 워크플로를 제출할 때 생성됩니다.
  - name: asset
    description: |
      지속적 에셋(이미지, 모델, 출력)을 업로드, 다운로드 및 관리합니다.
      에셋은 태그 지정 및 메타데이터 지원과 함께 내구성 있는 스토리지를 제공합니다.
  - name: file
    description: |
      로컬 ComfyUI와 호환되는 레거시 파일 업로드 및 다운로드 엔드포인트입니다.
      새로운 통합의 경우 Assets API 사용을 고려하세요.
  - name: model
    description: |
      사용 가능한 AI 모델을 찾아보세요. 모델은 클라우드 인프라에 사전 로드됩니다.
  - name: node
    description: |
      사용 가능한 ComfyUI 노드 및 해당 입력/출력에 대한 정보를 가져옵니다.
      동적 워크플로 인터페이스 구축에 유용합니다.
  - name: user
    description: |
      사용자 계정 정보 및 개인 데이터 스토리지.
  - name: system
    description: |
      서버 상태, 상태 확인 및 시스템 정보.
paths:
  /api/jobs:
    get:
      tags:
        - job
      summary: 페이지네이션 및 필터링으로 작업 목록 조회
      description: |
        인증된 사용자의 작업 목록을 페이지네이션으로 조회합니다.
        목록 보기에 최적화된 경량 작업 데이터를 반환합니다.
        페이로드 크기 감소를 위해 워크플로 및 전체 출력은 제외됩니다.
      operationId: listJobs
      parameters:
        - name: status
          in: query
          required: false
          description: 하나 이상의 상태로 필터링(쉼표로 구분). 제공되지 않으면 모든 작업을 반환합니다.
          schema:
            type: string
          example: pending,in_progress
        - name: workflow_id
          in: query
          required: false
          description: 워크플로 ID로 필터링(정확히 일치)
          schema:
            type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: output_type
          in: query
          required: false
          description: 출력 미디어 유형으로 필터링(출력이 있는 완료된 작업에만 적용)
          schema:
            type: string
            enum:
              - image
              - video
              - audio
          example: image
        - name: sort_by
          in: query
          required: false
          description: 정렬 기준 필드 (create_time = 작업이 제출된 시간, execution_time = 워크플로 실행에 걸린 시간)
          schema:
            type: string
            enum:
              - create_time
              - execution_time
            default: create_time
          example: execution_time
        - name: sort_order
          in: query
          required: false
          description: 정렬 방향 (asc = 오름차순, desc = 내림차순)
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: offset
          in: query
          required: false
          description: 페이지네이션 오프셋 (0부터 시작)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          description: 페이지당 최대 항목 수 (1-1000)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
      responses:
        '200':
          description: '성공: 작업 검색됨'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobsListResponse'
        '401':
          description: '인증되지 않음: 인증 필수'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 내부 서버 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    JobsListResponse:
      type: object
      required:
        - jobs
        - pagination
      properties:
        jobs:
          type: array
          description: 지정된 정렬 필드에 따라 정렬된 작업 배열
          items:
            $ref: '#/components/schemas/JobEntry'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    JobEntry:
      type: object
      description: 목록 보기를 위한 경량 작업 데이터 (워크플로 및 전체 출력 제외)
      required:
        - id
        - status
        - create_time
      properties:
        id:
          type: string
          format: uuid
          description: 고유 작업 식별자
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - failed
            - cancelled
          description: 사용자 친화적인 작업 상태
        execution_error:
          $ref: '#/components/schemas/ExecutionError'
          description: ComfyUI의 상세 실행 오류 (구조화된 오류 데이터가 있는 실패한 작업에만 해당)
        create_time:
          type: integer
          format: int64
          description: 작업 생성 타임스탬프 (초 단위 Unix 타임스탬프)
        preview_output:
          type: object
          description: 기본 출력 미리보기 (터미널 상태에만 있음)
          additionalProperties: true
        outputs_count:
          type: integer
          description: 출력 파일 총 개수 (비터미널 상태에서는 생략됨)
        workflow_id:
          type: string
          description: 워크플로 그래프 정의를 식별하는 UUID
        execution_start_time:
          type: integer
          format: int64
          description: 워크플로 실행 시작 타임스탬프 (Unix 밀리초, 터미널 상태에만 있음)
        execution_end_time:
          type: integer
          format: int64
          description: 워크플로 실행 완료 타임스탬프 (Unix 밀리초, 터미널 상태에만 있음)
    PaginationInfo:
      type: object
      required:
        - offset
        - limit
        - total
        - has_more
      properties:
        offset:
          type: integer
          minimum: 0
          description: 현재 오프셋(0부터 시작)
        limit:
          type: integer
          minimum: 1
          description: 페이지당 항목 수
        total:
          type: integer
          minimum: 0
          description: 필터와 일치하는 총 항목 수
        has_more:
          type: boolean
          description: 이 페이지 이후에 추가 항목이 있는지 여부
    ExecutionError:
      type: object
      description: ComfyUI의 상세한 실행 오류 정보
      required:
        - node_id
        - node_type
        - exception_message
        - exception_type
        - traceback
        - current_inputs
        - current_outputs
      properties:
        node_id:
          type: string
          description: 실패한 노드의 ID
        node_type:
          type: string
          description: '노드의 유형 이름 (예: "KSampler")'
        exception_message:
          type: string
          description: 사람이 읽을 수 있는 오류 메시지
        exception_type:
          type: string
          description: 'Python 예외 유형 (예: "RuntimeError")'
        traceback:
          type: array
          items:
            type: string
          description: 역추적 라인의 배열 (사용 불가 시 빈 배열)
        current_inputs:
          type: object
          additionalProperties: true
          description: 실패 시점의 입력 값 (사용 불가 경우 빈 객체)
        current_outputs:
          type: object
          additionalProperties: true
          description: 실패 시점의 출력 값 (사용 불가 시 빈 객체)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API 키 인증. 계정 설정에서 API 키를 생성하세요.

        https://platform.comfy.org/profile/api-keys 에서 생성할 수 있습니다. X-API-Key 헤더에
        키를 전달하세요.

````