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

# 查询通用任务

> 读取持久化任务状态、进度及时间戳。

`GET /v1/tasks/{key}`

此处 `key` 是公开任务 ID，和同路径 POST 的插件 key 不同。响应是已保存的状态，不主动触发上游查询。

`status` 为大写状态，`progress` 为展示字符串，`fail_reason` 不应未经处理公开。`created_at` / `finished_at` 是时间戳，未完成时后者可能为 0。任务不存在或不属于当前权限范围时返回 404；结果被丢弃的任务仍可读取状态，但不能据此假定产物可下载。状态与完成判断见[任务指南](/zh/guides/tasks)。

[Read in English](/en/api-reference/tasks-retrieve)


## OpenAPI

````yaml openapi/relay.json GET /v1/tasks/{key}
openapi: 3.0.3
info:
  title: API — Core inference API
  version: 0.5.0
  description: >-
    面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire
    management or provider API.
  license:
    name: AGPL-3.0-or-later
servers:
  - url: https://gateway.example.com
    description: >-
      Example only; replace with your gateway origin and optional path prefix,
      without /v1.
security:
  - BearerAuth: []
paths:
  /v1/tasks/{key}:
    get:
      summary: 查询通用任务 / Retrieve a task
      description: >-
        读取保存的任务状态，即使结果已丢弃也可能可读 / Read persisted task state, which can remain
        accessible even if results were discarded.
      operationId: tasks_retrieve
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            读取业务字段，不只检查 HTTP 状态 / Validate business fields, not only HTTP
            status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                  platform:
                    type: string
                  status:
                    type: string
                    enum:
                      - NOT_START
                      - SUBMITTED
                      - QUEUED
                      - IN_PROGRESS
                      - SUCCESS
                      - FAILURE
                      - NEEDS_REVIEW
                      - UNKNOWN
                  progress:
                    type: string
                  fail_reason:
                    type: string
                  created_at:
                    type: integer
                  finished_at:
                    type: integer
                additionalProperties: true
                required:
                  - task_id
                  - status
              example:
                task_id: task_example
                platform: example
                status: IN_PROGRESS
                progress: 50%
                fail_reason: ''
                created_at: 1700000000
                finished_at: 0
        default:
          description: 错误格式与状态取决于入口 / Error status and shape depend on the entry.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

````

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