Skip to content
helping.io
Get an API key

API reference

Retrieve a stored response by id.

GET
/responses/{response_id}
curl --request GET \
  --url https://api.helping.io/v1/responses/example \
  --header 'Authorization: Bearer <token>'

Returns the response’s current state, including its usage, which is why this is the endpoint to use for reconciling what a request cost. A response that failed comes back as a normal 200 whose object carries status: "failed" and an error.

Only the key that created a response can retrieve it. An id you cannot access and an id that does not exist both answer 404.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
response_id
required
string

Query Parameters

Section titled “Query Parameters”
include
Array<string>
Allowed values: reasoning.encrypted_content message.output_text.logprobs message.input_image.image_url file_search_call.results web_search_call.results web_search_call.action.sources computer_call_output.output.image_url code_interpreter_call.outputs

Extras to return that are omitted by default.

Responses

Section titled “ Responses ”

200

Section titled “200”

The stored response.

Media typeapplication/json

A response: one model turn, with everything it produced and the settings it ran under.

The settings are echoed back as they were applied, which is not always what you sent: values you omitted are filled in, and values capped by your organization’s policy are reported at the capped figure.

object
background
required
boolean
completed_at
required
integer | null format: int64
conversation
Any of:

The conversation a response belongs to.

Its items are the context the response ran on, and the response’s own input and output are added to it.

object
id
required

The conversation’s opaque id, conv_....

string
created_at
required
integer format: int64
error
required
Any of:

Why a response failed, carried on the response object itself.

A response that fails after it started is not an HTTP error: the request succeeds and the response object carries status: "failed" and this.

object
code
required
string
message
required
string
frequency_penalty
required
number format: double
id
required
string
incomplete_details
required
Any of:

Why a response stopped before it was finished.

object
reason
required
string
instructions
required
string | null
max_output_tokens
required
integer | null format: int64
max_tool_calls
required

The maximum number of tool calls this response was allowed to make.

The max_tool_calls sent with the request that started the turn, and null when that request sent none. A request that sends tool output keeps that value: a max_tool_calls sent with it is ignored.

integer | null format: int64
metadata
required

Whatever metadata you attached to the request, echoed back.

Always present, and null when you attached none.

model
required
string
object
required

Always response.

string
output
required
Array
One of:

One item of output, discriminated by type.

object
content
required
Array
One of:

Text you are sending to the model.

object
text
required
string
type
required
string
Allowed values: input_text
id
required
string
phase
Any of:

Whether an assistant message is the answer or commentary alongside it.

final_answer marks the message meant as the reply; commentary marks narration produced on the way there.

string
Allowed values: commentary final_answer
role
required

Who a message came from.

string
Allowed values: user assistant system developer
status
required

How far along an output item is.

in_progress while the item is still being produced, completed when it is final, and incomplete when the response stopped before the item was finished.

string
Allowed values: in_progress completed incomplete
type
required
string
Allowed values: message
parallel_tool_calls
required
boolean
presence_penalty
required
number format: double
previous_response_id
required
string | null
prompt_cache_key
required
string | null
reasoning
required
Any of:

Reasoning settings.

On a response this reports the settings that applied. This API does not accept it on a request: sending this field is refused rather than ignored.

object
effort
Any of:

How much reasoning the model should spend before answering.

Higher settings trade latency and cost for more deliberation. none disables reasoning where the model supports doing so.

string
Allowed values: none low medium high xhigh
summary
Any of:

How much of the model’s reasoning to summarize back to you, when a summary is produced at all.

string
Allowed values: concise detailed auto
safety_identifier
required
string | null
service_tier
required

The service tier this response ran under.

string
status
required

Where this response is in its lifecycle.

One of queued, in_progress, completed, failed, incomplete, or cancelled. queued and in_progress mean it is still running and can be retrieved again later; the rest are terminal. Treat it as an open string so a status added later does not break your client.

string
store
required
boolean
temperature
required
number format: double
text
required

Settings for the response text.

object
format
Any of:
One of:
object
type
required
string
Allowed values: text
verbosity
Any of:

How much detail to aim for in the response text.

string
Allowed values: low medium high
tool_choice
required
One of:

The string form of tool_choice.

auto lets the model decide whether to call a tool, required makes it call one, and none forbids tool calls for this turn.

string
Allowed values: none auto required
tools
required
Array
One of:

A tool offered to the model, discriminated by type.

object
description
string | null
name
required
string
parameters
strict
boolean | null
type
required
string
Allowed values: function
top_logprobs
required
integer format: int64
top_p
required
number format: double
truncation
required

What to do when a conversation no longer fits the model’s context window.

auto lets the OLDEST turns be dropped so the request can proceed; disabled fails the request instead of dropping anything, and is the default (OpenAI’s default too).

Oldest-first is the same end OpenAI documents dropping from: their own API reference words auto as “dropping items from the beginning of the conversation”. The turn the caller just sent is never a candidate.

string
Allowed values: auto disabled
usage

What this response consumed.

ABSENT while the response is still running, and present once it settles. A response that is queued or in_progress has spent nothing you can be billed for yet, so there is no figure to report, and the field is left out rather than sent as null.

object
input_tokens
required
integer format: int64
input_tokens_details
required

A breakdown of the input tokens counted.

Both fields are SUBSETS of input_tokens, not additions to it.

object
cache_write_tokens
required

Input tokens written INTO the provider’s prompt cache.

A provider that does not charge for a cache write reports 0 here.

integer format: int64
cached_tokens
required

Input tokens served from the provider’s prompt cache.

integer format: int64
output_tokens
required
integer format: int64
output_tokens_details
required

A breakdown of the output tokens counted.

object
reasoning_tokens
required
integer format: int64
total_tokens
required
integer format: int64
Example
{
  "output": [
    {
      "content": [
        {
          "type": "input_text"
        }
      ],
      "phase": "commentary",
      "role": "user",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tool_choice": "none",
  "tools": [
    {
      "type": "function"
    }
  ],
  "truncation": "auto"
}

400

Section titled “400”

An include value this API does not recognize, or a query parameter this endpoint does not support.

401

Section titled “401”

Missing or invalid API key (the error envelope)

403

Section titled “403”

The key is not entitled to what the request asked for (the error envelope)

404

Section titled “404”

No such response, or one this key cannot reach.

429

Section titled “429”

This organization has exhausted its retrieval allowance; retry after the Retry-After header.

500

Section titled “500”

The request could not be completed; quote the x-request-id response header when reporting it.

503

Section titled “503”

The request could not be served this instant; retry after the Retry-After header.

© 2026 helping.io