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

# 列出 Midjourney 任務

> POST /mj/task/list-by-condition 會依據篩選條件列出 Midjourney 任務，以擷取一個或多個工作的狀態，包括進度與結果。

當你需要一次擷取一批 Midjourney 任務，而不是每次輪詢一個 task id 時，請使用這個端點。

## 何時使用

* 你正在同時追蹤多個 Midjourney 任務
* 你想依照任務狀態、提交時間範圍或其他伺服器端條件進行篩選
* 你需要的是儀表板或對帳工作，而不是互動式的單一任務輪詢

## 查詢模式

<Steps>
  <Step title="針對高頻路徑使用單一任務輪詢">
    對於單一進行中的任務，建議優先使用 [擷取單一任務](./fetch-single-task)，因為這樣更簡單也更快。
  </Step>

  <Step title="針對批次檢查使用條件式列表">
    當你需要在一次請求中檢視多個 Midjourney 任務時，請透過此端點傳送你的篩選條件。
  </Step>

  <Step title="後續追蹤值得關注的任務">
    當批次結果顯示有些任務需要更深入檢查或繼續處理時，請切回使用 [擷取單一任務](./fetch-single-task) 和 [操作](../action)。
  </Step>
</Steps>

<Tip>
  將此路由用於監控與對帳工作；主要的互動式輪詢路徑請使用 [擷取單一任務](./fetch-single-task)。
</Tip>


## OpenAPI

````yaml api/openapi/image/midjourney/task-fetching-api/post-list-by-condition.openapi.json POST /mj/task/list-by-condition
openapi: 3.1.0
info:
  title: List by Condition API
  version: 1.0.0
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /mj/task/list-by-condition:
    post:
      summary: List by Condition
      operationId: list_by_condition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ids
              properties:
                ids:
                  type: array
                  description: >-
                    Array of Midjourney task ids to retrieve. Returns the
                    current status and result for each.
                  items:
                    type: string
                  default:
                    - example
              default:
                ids:
                  - example
            examples:
              Default:
                summary: Fetch several tasks by id
                value:
                  ids:
                    - <task_id>
                    - <task_id>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    action:
                      type: string
                      description: >-
                        Task type: `IMAGINE`, `UPSCALE`, `VARIATION`,
                        `DESCRIBE`, `BLEND`, `VIDEO`, or another action name.
                    buttons:
                      type: array
                      items:
                        type: object
                        properties:
                          customId:
                            type: string
                          emoji:
                            type: string
                          label:
                            type: string
                          style:
                            type: integer
                          type:
                            type: integer
                      description: >-
                        Action buttons available on the finished task. Send a
                        button's `customId` together with this task's id to
                        `/mj/submit/action` to upscale, vary, zoom, or pan.
                    description:
                      type: string
                      description: Human-readable submission status message.
                    failReason:
                      type: string
                      description: Failure reason when `status` is `FAILURE`.
                    finishTime:
                      type: integer
                      description: Completion time as a Unix timestamp in milliseconds.
                    id:
                      type: string
                      description: Task id.
                    imageUrl:
                      type: string
                      description: >-
                        Stable CometAPI-proxied image link
                        (`https://api.cometapi.com/mj/image/{id}`). Prefer this
                        link; entries in `image_urls` point at provider storage
                        and can expire.
                    progress:
                      type: string
                      description: >-
                        Progress percentage string such as `58%` while the task
                        runs and `100%` when finished.
                    prompt:
                      type: string
                      description: Original prompt as submitted.
                    promptEn:
                      type: string
                      description: >-
                        Prompt after translation to the provider language. For
                        `DESCRIBE` tasks, the extracted prompt suggestions
                        arrive here.
                    properties:
                      type: object
                      properties: {}
                      description: Additional task metadata, such as `finalPrompt`.
                    startTime:
                      type: integer
                      description: >-
                        Processing start time as a Unix timestamp in
                        milliseconds.
                    state:
                      type: string
                      description: >-
                        Custom state string echoed back from the submission for
                        your own tracking.
                    status:
                      type: string
                      description: >-
                        Task lifecycle state: `NOT_START`, `SUBMITTED`,
                        `IN_PROGRESS`, `SUCCESS`, or `FAILURE`.
                    submitTime:
                      type: integer
                      description: Submission time as a Unix timestamp in milliseconds.
      x-codeSamples:
        - lang: Shell
          label: Default
          source: |
            curl https://api.cometapi.com/mj/task/list-by-condition \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "ids": ["<task_id>", "<task_id>"]
              }'
        - lang: Python
          label: Default
          source: |
            import os
            import requests

            response = requests.post(
                "https://api.cometapi.com/mj/task/list-by-condition",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={"ids": ["<task_id>", "<task_id>"]},
            )

            for task in response.json():
                print(task["id"], task["action"], task["status"], task.get("progress"))
        - lang: JavaScript
          label: Default
          source: >
            const response = await
            fetch("https://api.cometapi.com/mj/task/list-by-condition", {
                method: "POST",
                headers: {
                    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({ ids: ["<task_id>", "<task_id>"] }),
            });


            for (const task of await response.json()) {
                console.log(task.id, task.action, task.status, task.progress);
            }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````