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

# Retrieve a plugin task response

> Read Responses state and output for a platform plugin task.

`GET /v1/responses/{response_id}`

Use a Bearer token and the complete `response_id` returned by creation, with no request body. GET with an ID returns a JSON snapshot; `GET /v1/responses` without an ID is a WebSocket upgrade endpoint.

The implementation reads platform task records; it does not proxy GET to ordinary upstreams. Only retrievable plugin tasks belonging to the same user and project are returned. Invalid or inaccessible IDs, discarded results, or unresolved plugins can return 404. Do not automatically resubmit a task in response.

Check `status` and `error` even with HTTP 200. queued / in\_progress means wait; after completed, validate results according to output type. failed is not success. Rendering a final task result can also fail and return a failed response object.

SSE resumption, input\_items, REST cancel, and delete are not provided. See [background mode and bounded polling](/en/guides/background-responses.md).

[阅读中文](/zh/api-reference/responses-retrieve.md)


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