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

# 查询插件任务响应

> 读取本平台插件任务的 Responses 状态与输出。

`GET /v1/responses/{response_id}`

使用 Bearer 令牌和创建请求返回的完整 `response_id`，无请求体。此处的 GET 含 ID，用于 JSON 快照；不含 ID 的 `GET /v1/responses` 是 WebSocket 升级入口。

当前查询实现读取本平台任务记录，不向普通上游代理 GET。只返回同一用户、同一项目且结果可检索的插件任务。ID 错误、不可见、结果已丢弃或插件无法解析时可能返回 404，不应自动重新提交任务。

HTTP 200 仍要检查 `status` 和 `error`。queued / in\_progress 表示继续等待；completed 后再按 output 类型校验业务结果；failed 不代表成功。任务最终结果渲染失败也可能表现为失败的响应对象。

不提供 SSE 续传、input\_items、REST cancel 或 delete。见[后台模式与有界轮询示例](/zh/guides/background-responses)。

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


## OpenAPI

````yaml openapi/relay.json GET /v1/responses/{response_id}
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/responses/{response_id}:
    get:
      summary: 查询插件任务响应 / Retrieve a plugin task response
      description: >-
        仅查询同一用户和项目内、结果未丢弃的宿主插件任务；不代理普通上游检索 / Only retained host plugin tasks
        within the same user and project; not ordinary upstream retrieval
      operationId: retrieveTaskResponse
      parameters:
        - name: response_id
          in: path
          required: true
          schema:
            type: string
          description: 经过 URL 编码的完整标识 / Complete URL-encoded identifier
      responses:
        '200':
          description: 成功结构仍需检查业务字段 / Check business fields even on HTTP success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
              example:
                id: resp_example
                object: response
                created_at: 1700000000
                model: YOUR_MODEL_ID
                status: queued
                background: true
                output: []
                error: null
                usage: null
        '400':
          description: 请求参数错误 / Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 身份校验失败 / Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 访问被拒绝 / Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 接口或资源不存在 / Endpoint or resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 请求被限流或受配额限制 / Rate or quota restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 网关或上游错误 / Gateway or upstream error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 服务暂不可用 / Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: 其他网关或上游错误；格式可能不同 / Other gateway or upstream error; shape may vary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        created_at:
          type: number
        model:
          type: string
        status:
          type: string
          description: >-
            必须检查完成状态，例如 completed、failed、incomplete / Check completion status,
            for example completed, failed, or incomplete
        output:
          type: array
          items:
            $ref: '#/components/schemas/OutputItem'
        error:
          type: object
          nullable: true
          additionalProperties: true
        incomplete_details:
          type: object
          nullable: true
          additionalProperties: true
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            total_tokens:
              type: integer
            input_tokens_details:
              type: object
              nullable: true
              properties:
                cached_tokens:
                  type: integer
                  description: >-
                    报告的缓存读取 token；缺失不等于零，不代表最终账单 / Reported cache-read tokens;
                    absence is not zero and this is not an invoice
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
                cache_write_tokens:
                  type: integer
                  description: >-
                    支持渠道报告的缓存写入 token；不要跨协议机械相加 / Cache-write tokens reported by
                    supporting channels; do not mechanically sum across
                    protocols
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
              additionalProperties: true
            output_tokens_details:
              type: object
              nullable: true
              properties:
                reasoning_tokens:
                  type: integer
                  description: >-
                    报告的推理 token；可能缺失，不等同于可见文本长度 / Reported reasoning tokens; may
                    be absent, not visible text length
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
              additionalProperties: true
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              nullable: true
              description: 错误标识；类型随上游变化 / Error identifier; type varies by upstream
    OutputItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          example: message
        role:
          type: string
          example: assistant
        status:
          type: string
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: output_text
              text:
                type: string
              annotations:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: url_citation
                    url:
                      type: string
                    title:
                      type: string
                    start_index:
                      type: integer
                    end_index:
                      type: integer
                  additionalProperties: true
                description: >-
                  引用偏移属于该原始文本块；不要合并后复用索引 / Citation offsets belong to this
                  original text block; do not reuse after merging
              refusal:
                type: string
                description: type 为 refusal 时的拒答文本 / Refusal text when type is refusal
        call_id:
          type: string
          description: >-
            function_call 的结果关联 ID，不等同于输出项 id / Correlates function_call
            results; distinct from the output item id
        name:
          type: string
          description: function_call 的函数名称 / Function name for a function_call
        arguments:
          type: string
          description: >-
            函数参数的 JSON 字符串；执行前校验 / JSON-encoded function arguments; validate
            before execution
        summary:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              text:
                type: string
          description: 推理摘要项；可能为空 / Reasoning summary items; may be empty
        encrypted_content:
          type: string
          description: >-
            支持的渠道返回的不透明推理状态；原样保留，不解码 / Opaque reasoning state returned by
            supporting channels; preserve without decoding
        phase:
          type: string
          description: >-
            支持的模型返回的消息阶段；重放时保留 / Message phase returned by supporting models;
            preserve when replaying
      description: >-
        也可能是工具调用、推理或其他输出项；不要假定第一项就是文本 / May also be a tool, reasoning, or other
        output item; do not assume the first item is text；原生搜索项可为
        web_search_call，检查其 status / Native search items may use
        web_search_call; check their status
      x-source-files:
        - relaykit/dto/openai_request.go
        - relay/channel/openai/relay-openai.go
        - relay/common/relay_info.go
  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.