Text
Retrieve Response
Retrieves a stored response by ID, or polls a background response.
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
storenot set tofalse, andbackgroundresponses. Withstore: 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, orcancelled. Checkstatus, 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.
Request
curl -X GET "https://api.tokenlab.sh/v1/responses/resp_abc123" \
-H "Authorization: Bearer sk-your-api-key"Response
{
"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
| Status | Code | Meaning |
|---|---|---|
404 | response_not_found | The ID is unknown, belongs to another account, was deleted, was created with store: false, or is past its retention. |
502 | upstream_response_read_failed | TokenLab could not read the response from the service that produced it. Retry later. |
503 | response_state_unavailable, response_result_unavailable | The response state is temporarily unavailable. Retry later. |
Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Path Parameters
Response id returned by POST /v1/responses.
Query Parameters
Additional response fields to include, forwarded where the model supports them.
Whether streamed events include obfuscation fields, forwarded where the model supports it.
Whether to retrieve the response as an event stream. Applies while the response is still running; a finished response is returned as JSON.
Sequence number after which streaming events are returned. Applies only with stream.
Response
application/json
application/json
application/json
application/json