Retrieve a stored response

GET

/responses/{response_id}

curl --request GET \
  --url https://api.katara.com/v1/responses/example \
  --header 'Authorization: Bearer <token>'

• Test and Live. The key decides which network a request is served on.

A response stored with a key is read with a key of the same account; one stored without a key, by whoever holds its id. Reads do not extend its 30-day retention.

Authorizations

• bearerAuth
• None

Parameters

Path Parameters

response_id

required

string

/^resp_[A-Za-z0-9_-]{1,120}$/

The id of a stored response.

Responses

200

The stored response.

Media typeapplication/json

object

id

required

string

object

required

string

Allowed value: response

created_at

required

Unix seconds.

integer

status

required

string

Allowed values: in_progress completed incomplete failed

model

required

string

Allowed value: katara/cortex

previous_response_id

string | null

output

required

Assistant messages with output_text (and url_citation annotations for pages the answer quotes), function_call and custom_tool_call items, reasoning items and web_search_call items with their sources.

Array<object>

object

id

string

type

string

Allowed values: message reasoning function_call custom_tool_call web_search_call

status

string

Allowed values: in_progress completed incomplete

role

string

Allowed value: assistant

call_id

string

name

string

arguments

string

input

string

content

Array<object>

object

type

string

Allowed values: output_text reasoning_text

text

string

annotations

Array<object>

object

key

additional properties

any

key

additional properties

any

key

additional properties

any

usage

required

object

input_tokens

integer

output_tokens

integer

total_tokens

integer

input_tokens_details

object

cached_tokens

integer

cache_write_tokens

integer

output_tokens_details

object

reasoning_tokens

integer

katara

Any of:

object

What this reply cost.

object

cost_usdc

required

The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).

string

cost_usd

The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.

string

billing_method

string

Allowed values: credits usdc

payment

On a request paid with x402, the payment that settles the reply.

object

scheme

string

Allowed values: upto exact

network

string

asset

The token paid.

string

amount

The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.

string

provider

The provider’s address, or managed when a vendor answered.

string

cached_tokens

Prompt tokens the vendor read from its cache, billed at the cached input rate.

integer

cache_saving_usdc

What the cached tokens saved against the input rate, in USDC.

string

cache_saving_usd

The same saving in Credits, on a reply paid with account credits.

string

compaction

When katara.compaction summarised the conversation.

object

message

The system message to send in place of the summarised messages.

object

replaces_from

First index in this request’s messages that the summary replaces.

integer

replaces_to

First index kept after it.

integer

model

string

tokens_before

integer

summary

The summary request’s usage and its cost (cost_usdc or cost_usd).

object

skipped

Why no summary was made; the request went whole.

string

context_edits

object

cleared_tool_results

integer

cleared_tokens

integer

through_turn

integer

cache_written_tokens

Tokens this request wrote to a new explicit cache (katara.cache).

integer

cache_ttl_seconds

How long that cache is kept.

integer

cache_storage_usdc

What keeping it costs, in USDC; included in cost_usdc.

string

simulated

On Test, a reply with fixed text that no model wrote, served when no Test provider was free.

boolean

stop_sequence

The stop sequence at which Katara ended the reply.

string

web_search

The searches this request was charged for.

object

requests

The successful searches; only those are charged, and none when the request ended without an answer.

integer

cost_usdc

string

cost_usd

string

model_calls

On a web search request, how many model calls it made.

integer

web_searches

Every search the model made, in order. Not on stream chunks, which carry each search as it runs.

Array<object>

object

id

required

string

query

required

string

results

required

Array<object>

object

url

string

title

string

page_age

string

content

string

error

string

Allowed values: invalid_input query_too_long too_many_requests unavailable max_uses_exceeded insufficient_quota

edit_id

On an image reply from a model that edits, the id to send as previous_edit_id.

string

object

What this reply cost.

object

cost_usdc

The settled price, in USDC, as a decimal string. For a request paid with x402 it is the charge, the model’s minimum included (0.025 USDC, 0.05 for katara/cortex-genius, 0.01 for katara/cortex-smart).

string

cost_usd

required

The Credits charge as a decimal string. This legacy field name is retained for compatibility; display Credits without a dollar sign.

string

billing_method

string

Allowed values: credits usdc

payment

On a request paid with x402, the payment that settles the reply.

object

scheme

string

Allowed values: upto exact

network

string

asset

The token paid.

string

amount

The charge in the token’s base units, the same as amount in PAYMENT-RESPONSE.

string

provider

The provider’s address, or managed when a vendor answered.

string

cached_tokens

Prompt tokens the vendor read from its cache, billed at the cached input rate.

integer

cache_saving_usdc

What the cached tokens saved against the input rate, in USDC.

string

cache_saving_usd

The same saving in Credits, on a reply paid with account credits.

string

compaction

When katara.compaction summarised the conversation.

object

message

The system message to send in place of the summarised messages.

object

replaces_from

First index in this request’s messages that the summary replaces.

integer

replaces_to

First index kept after it.

integer

model

string

tokens_before

integer

summary

The summary request’s usage and its cost (cost_usdc or cost_usd).

object

skipped

Why no summary was made; the request went whole.

string

context_edits

object

cleared_tool_results

integer

cleared_tokens

integer

through_turn

integer

cache_written_tokens

Tokens this request wrote to a new explicit cache (katara.cache).

integer

cache_ttl_seconds

How long that cache is kept.

integer

cache_storage_usdc

What keeping it costs, in USDC; included in cost_usdc.

string

simulated

On Test, a reply with fixed text that no model wrote, served when no Test provider was free.

boolean

stop_sequence

The stop sequence at which Katara ended the reply.

string

web_search

The searches this request was charged for.

object

requests

The successful searches; only those are charged, and none when the request ended without an answer.

integer

cost_usdc

string

cost_usd

string

model_calls

On a web search request, how many model calls it made.

integer

web_searches

Every search the model made, in order. Not on stream chunks, which carry each search as it runs.

Array<object>

object

id

required

string

query

required

string

results

required

Array<object>

object

url

string

title

string

page_age

string

content

string

error

string

Allowed values: invalid_input query_too_long too_many_requests unavailable max_uses_exceeded insufficient_quota

edit_id

On an image reply from a model that edits, the id to send as previous_edit_id.

string

metadata

object | null

incomplete_details

object

reason

string

Allowed values: max_output_tokens content_filter

error

object

code

string

message

string

Example

{
  "object": "response",
  "status": "in_progress",
  "model": "katara/cortex",
  "output": [
    {
      "type": "message",
      "status": "in_progress",
      "role": "assistant",
      "content": [
        {
          "type": "output_text"
        }
      ]
    }
  ],
  "katara": {
    "cost_usdc": "0.000018",
    "cost_usd": "0.000018",
    "billing_method": "credits",
    "payment": {
      "scheme": "upto",
      "network": "eip155:43114",
      "amount": "25000"
    },
    "web_searches": [
      {
        "error": "invalid_input"
      }
    ]
  },
  "incomplete_details": {
    "reason": "max_output_tokens"
  }
}

400

stream=true was asked for (unsupported_parameter).

Media typeapplication/json

object

error

required

object

type

string

code

required

Stable error code.

string

message

required

Explanation for the caller.

string

param

string | null

Example^generated

{
  "error": {
    "type": "example",
    "code": "example",
    "message": "example",
    "param": "example"
  }
}

404

The response is missing, expired, deleted or someone else’s (response_not_found).

Media typeapplication/json

object

error

required

object

type

string

code

required

Stable error code.

string

message

required

Explanation for the caller.

string

param

string | null

Example^generated

{
  "error": {
    "type": "example",
    "code": "example",
    "message": "example",
    "param": "example"
  }
}