> ## 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.

# List Midjourney tasks

> POST /mj/task/list-by-condition lists Midjourney tasks by filters to fetch status for one or multiple jobs, including progress and results.

Use this endpoint when you need to retrieve a batch of Midjourney tasks instead of polling one task id at a time.

## When to use it

* You are tracking many Midjourney tasks together
* You want to filter by task state, submission window, or other server-side conditions
* You need a dashboard or reconciliation job instead of an interactive single-task poll

## Query pattern

<Steps>
  <Step title="Use single-task polling for hot paths">
    For one active task, prefer [Fetch Single Task](./fetch-single-task), because it is simpler and faster.
  </Step>

  <Step title="Use condition-based listing for batch checks">
    Send your filter conditions through this endpoint when you need to inspect multiple Midjourney tasks in one request.
  </Step>

  <Step title="Follow up on interesting tasks">
    When the batch result shows tasks that need deeper inspection or continuation, switch back to [Fetch Single Task](./fetch-single-task) and [Action](../action).
  </Step>
</Steps>

<Tip>
  Use this route for monitoring and reconciliation jobs; use [Fetch Single Task](./fetch-single-task) for the main interactive polling path.
</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.

````