# Retrieve a Response

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Retrieve a stored Response. Full-output retrieval and retention depend on the selected model service.

```text
GET https://token.moi.matrixorigin.cn/v1/responses/$RESPONSE_ID
```

## Before you begin

1. [Create a Response](../text-generation/responses.md#request-body) with storage enabled on a model service that supports storage and retrieval. Select a response that is still accessible and has not been deleted or expired.
2. Prepare the [personal access token](../../../../guides/billing/credentials.md#personal-access-token) used to create that response.

## Request example

Replace `$GENESIS_ACCESS_TOKEN` and `$RESPONSE_ID` with your personal access token and the selected response ID.

```bash
curl -X GET \
  "https://token.moi.matrixorigin.cn/v1/responses/$RESPONSE_ID" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN"
```

## Path parameters

::::{div} mo-api-parameter-table

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `response_id` | string | Yes | Stored Response identifier from `id` in the create response result. |

::::

## Successful response

A successful request returns the stored response. Full content depends on the selected model service’s storage support.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "id": "resp-example",
  "object": "response",
  "status": "completed",
  "model": "MODEL_ID",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "OK"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 1,
    "total_tokens": 13
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Response identifier; use it to retrieve or delete a stored response. |
| `object` | string | Object type `response`. |
| `status` | string | Generation status, such as `completed`; check it to determine whether output is complete. |
| `model` | string | Model that processed the request. |
| `output` | array of object | Output items; text messages may follow reasoning items. |
| `output[].type` | string | Output type, such as `message` or `reasoning`. |
| `output[].role` | string | Role of a message output item. |
| `output[].content` | array of object | Content blocks in a message output item. |
| `output[].content[].type` | string | Generated text blocks use `output_text`. |
| `output[].content[].text` | string | Generated text. |
| `output[].summary` | array of object | Summary returned with a reasoning item, when present. |
| `output[].summary[].type` | string | Summary block type, such as `summary_text`. |
| `output[].summary[].text` | string | Summary text. |
| `usage` | object | Token usage for this request. |
| `usage.input_tokens` | integer | Input tokens. |
| `usage.output_tokens` | integer | Output tokens. |
| `usage.total_tokens` | integer | Total tokens. |

:::::
::::::
:::::::

## Error response

HTTP `404` indicates a missing, deleted, expired, or inaccessible response. Check the response ID and the credentials used to create it.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "error": {
    "message": "response state not found",
    "type": "response_state_not_found",
    "code": "response_state_not_found"
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error details. |
| `error.message` | string | Description of an unavailable or missing response. |
| `error.type` | string | Error type. |
| `error.code` | string | Error code. |

:::::
::::::
:::::::

## Next steps

Use the same `id` to [List Response input items](list-input-items.md), or [Delete a Response](delete-response.md) when it is no longer needed.