TokenLab

Text

Retrieve Response

Retrieves a stored response by ID, or polls a background response.

GET
/v1/responses/{id}

Overview

Returns a response that Create Response created. Use it to poll a background response until its status is final, or to read a stored response again.

  • Which responses: Responses created with store not set to false, and background responses. With store: false, TokenLab keeps nothing to return.
  • Retention: TokenLab keeps a stored response for 24 hours. Some stay retrievable for up to 30 days, but do not rely on that: save the result you need. After its retention, the ID returns 404.
  • Ownership: You can read only responses created in your own account. An ID from another account returns 404, the same as an unknown ID.
  • Status: queued, in_progress, completed, incomplete, failed, or cancelled. Check status, not only the HTTP code.

stream and starting_after apply while a response is still running. A finished response is returned as JSON. include and include_obfuscation are forwarded where the model supports them.

Example

Request

cURL
curl -X GET "https://api.tokenlab.sh/v1/responses/resp_abc123" \
  -H "Authorization: Bearer sk-your-api-key"

Response example

Response

200 OK
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1706000000,
  "status": "completed",
  "model": "gpt-5.6-terra",
  "output": [
    {
      "id": "msg_abc123",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Hello! How can I help you today?", "annotations": []}
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 12,
    "total_tokens": 22
  }
}

Errors

StatusCodeMeaning
404response_not_foundThe ID is unknown, belongs to another account, was deleted, was created with store: false, or is past its retention.
502upstream_response_read_failedTokenLab could not read the response from the service that produced it. Retry later.
503response_state_unavailable, response_result_unavailableThe response state is temporarily unavailable. Retry later.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Path Parameters

id*string

Response id returned by POST /v1/responses.

Query Parameters

include?array<string>

Additional response fields to include, forwarded where the model supports them.

include_obfuscation?boolean

Whether streamed events include obfuscation fields, forwarded where the model supports it.

stream?boolean

Whether to retrieve the response as an event stream. Applies while the response is still running; a finished response is returned as JSON.

starting_after?integer

Sequence number after which streaming events are returned. Applies only with stream.

Response

application/json

application/json

application/json

application/json