> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve response
> Retrieves a previously created response by its ID.
**Related guide**: Responses API guide. See the [Responses API guide](/ai-gateway/features/responses-api) for a walkthrough with examples.
Retrieves a previously created response by its ID. The response must have been created with `store: true` (the default).
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://my.orq.ai/v3/router/responses/resp_01KP6GDNJY5B0TT0R35KS23PYV \
-H "Authorization: Bearer $ORQ_API_KEY"
```
```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "resp_01KP6GDNJY5B0TT0R35KS23PYV",
"object": "response",
"created_at": 1776187529,
"completed_at": 1776187529,
"status": "completed",
"model": "openai/gpt-6-astra",
"input": [
{
"type": "message",
"id": "msg_01KP6GDNK0TXBVMD3N5BWZ285J",
"role": "user",
"content": [
{ "type": "input_text", "text": "What time is it?" }
]
}
],
"output": [
{
"type": "orq:current_date",
"id": "msg_01kp6gdppk31xp6qc1z92x132p",
"call_id": "fc_888c598a-b519-421a-9904-e5f0e8c34a53",
"name": "current_date",
"status": "completed",
"result": {
"currentDate": "2026-04-14T17:25:29.175Z"
}
},
{
"type": "message",
"id": "msg_01KP6GDPP6D57H9G7VVFKFW07H",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "It's currently 17:25 UTC (2026‑04‑14).",
"annotations": []
}
]
}
],
"tools": [
{ "type": "orq:current_date" }
],
"usage": {
"input_tokens": 352,
"output_tokens": 126,
"total_tokens": 478,
"input_tokens_details": {
"cached_tokens": 0,
"cache_creation_tokens": 0
},
"output_tokens_details": {
"reasoning_tokens": 76
}
}
}
```
## OpenAPI
````yaml get /v3/router/responses/{response_id}
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Chunking
description: Split text into smaller chunks for retrieval and generation workflows.
- name: File Systems
description: >-
Create and manage persistent file systems that agents and MCP clients read
from and write to.
- name: Knowledge Bases
description: Create and manage knowledge bases used by agents and retrieval workflows.
- name: Memory Stores
description: Create and manage memory stores, memories, and memory documents.
- name: Evals
description: Run an evaluator against a conversation and its result
- name: Logs
description: >-
OpenTelemetry log query API. Search, filter, aggregate, and facet log
records ingested via OTLP.
- name: Reporting
description: >-
GenAI reporting API over canonical analytics rollups. Accepts a metric
name, time range, grain, group-by, and filters; returns a typed time
series and optional totals.
- name: Traces
description: >-
Query and inspect ingested trace data: search trace summaries, aggregate
metrics, and read individual traces and their spans.
- description: List models available through the AI Router.
name: Models
- name: Policies
- name: Alerts
description: >-
Alerts evaluate a Reporting API metric on a fixed interval and fire
notifications through notifiers when the value breaches a threshold. Each
breach opens a trigger that tracks the incident until the value recovers.
- name: Annotation Queues
description: Annotation queues collect spans for human review.
- name: API keys
description: >-
API keys authenticate programmatic access to the workspace. They expose
opaque tokens, per-domain access grants, and budget and rate-limit
constraints.
- name: Audit Logs
description: Audit logs record workspace entity changes and access-relevant events.
- name: Budgets
description: >-
Budgets govern spend, token usage, and request rate across six scopes:
workspace, project, identity, API key, provider, and model. Every
applicable budget is enforced, and the most restrictive limit applies per
dimension.
- name: Files
description: File upload and retrieval operations.
- name: Guardrail Rules
description: >-
Guardrail Rules conditionally enforce evaluators and plugins for AI
Gateway traffic. Rules may be scoped to a project or the whole workspace.
- name: Hub
description: Hub items are reusable templates available to a workspace.
- name: Identities
description: >-
Identities represent end users from your system for usage and engagement
tracking.
- name: Management keys
description: >-
Management keys are workspace-scoped credentials that authenticate
programmatic access to workspace administration surfaces (API keys,
budgets). Unlike project-scoped API keys, a management key always operates
at the workspace level.
- name: MCP Gateway
description: >-
Register upstream MCP servers, discover and sync their tools, and assemble
gateways that expose a curated tool surface to MCP clients.
- name: Model Catalog
description: >-
Browse the orq.ai model catalog: every model orq offers, across every
provider, with pricing, capabilities and benchmark data. List endpoints
only return models that are not deprecated. This API is public, requires
no authentication, and is rate limited to 120 requests per minute per IP.
Responses carry a 5-minute cache-control max-age.
- name: Notifiers
description: Notifier destinations used to send delivery and workflow notifications.
- name: Projects
description: Projects organize resources within a workspace
- name: Routing Rules
description: >-
Routing Rules conditionally select models and enforce request plugins for
AI Gateway traffic. Rules are evaluated by ascending priority and may be
scoped to a project or the whole workspace.
- name: Threads
description: Threads group related trace invocations and their aggregate usage
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: Smart Routers
description: >-
Create and manage workspace Smart Routers. A Smart Router selects a model
from an eligible pool for each request according to a quality, balanced,
or cost profile.
- name: Webhooks
description: >-
Create and manage webhooks that deliver workspace events to external HTTPS
endpoints.
- name: Workspaces
description: >-
A workspace is the tenant. Create is called from a user session during
onboarding; Get, List, and Update are the public management surface.
- name: Workspace Security
description: >-
Workspace-level domain verification and IP allowlist controls. These
operations are restricted to workspace administrators.
- name: Workspace Settings
description: >-
Workspace-level settings managed with a workspace credential. A workspace
is the tenant, so these settings are a singleton — there is nothing to
create or delete, only read and update.
- name: Responses
- description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
name: Agent Schedules
- name: Embeddings
- name: Telemetry
description: >-
Unified query envelope for traces, metrics, and logs. One request shape,
one filter dialect, and one response shape per source, validated by a
per-source registry.
- description: Beta. Run typed classification questions against a classify model.
name: Classify
- description: Search Gateway with managed credits or BYOK.
name: Web Search
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v3/router/responses/{response_id}:
get:
tags:
- Responses
summary: Retrieve response
description: Retrieves a previously created response by its ID.
operationId: retrieve-response
parameters:
- description: The ID of the response to retrieve
in: path
name: response_id
required: true
schema:
description: The ID of the response to retrieve
type: string
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
background:
type: boolean
completed_at:
format: int64
type:
- integer
- 'null'
conversation:
$ref: '#/components/schemas/ConversationParam'
created_at:
format: int64
type: integer
error:
anyOf:
- $ref: '#/components/schemas/ResponseError'
- type: 'null'
frequency_penalty:
type: number
format: double
id:
type: string
incomplete_details:
anyOf:
- $ref: '#/components/schemas/IncompleteDetails'
- type: 'null'
input:
description: >-
Array of input items (messages, function call outputs,
etc.)
items: {}
type:
- array
- 'null'
instructions:
type:
- string
- 'null'
max_output_tokens:
format: int64
type:
- integer
- 'null'
max_tool_calls:
format: int64
type:
- integer
- 'null'
memory:
$ref: '#/components/schemas/MemoryParam'
metadata:
additionalProperties:
type: string
description: >-
Developer-defined key-value pairs attached to the response
(OpenAI spec: Map).
type: object
model:
type: string
object:
description: Always "response"
type: string
output:
description: >-
Array of output items (messages, function calls,
reasoning, etc.)
items: {}
type:
- array
- 'null'
parallel_tool_calls:
type: boolean
presence_penalty:
type: number
format: double
previous_response_id:
type:
- string
- 'null'
prompt_cache_key:
type:
- string
- 'null'
prompt_cache_options:
anyOf:
- $ref: '#/components/schemas/OpenAIPromptCacheOptions'
- type: 'null'
prompt_cache_retention:
type:
- string
- 'null'
reasoning:
anyOf:
- $ref: '#/components/schemas/Reasoning'
- type: 'null'
safety_identifier:
type:
- string
- 'null'
service_tier:
enum:
- auto
- default
- flex
- fast
- scale
- priority
type: string
status:
enum:
- queued
- in_progress
- completed
- failed
- incomplete
type: string
store:
type: boolean
telemetry:
$ref: '#/components/schemas/ResponseTelemetry'
description: >-
OpenTelemetry trace and span identifiers for this
response.
temperature:
type: number
format: double
text:
description: Text output configuration including format and verbosity
tool_choice:
description: >-
Tool choice setting: "auto", "none", "required", or a
specific function
tools:
description: Array of tool configurations used in this response
items: {}
type:
- array
- 'null'
top_k:
description: >-
Only sample from the top K options for each subsequent
token. Present only when set on the request.
format: int64
type: integer
top_logprobs:
format: int64
type: integer
top_p:
type: number
format: double
truncation:
enum:
- disabled
- auto
type: string
usage:
anyOf:
- $ref: '#/components/schemas/PublicUsage'
- type: 'null'
user:
type:
- string
- 'null'
variables:
type: object
additionalProperties: {}
required:
- id
- object
- created_at
- completed_at
- status
- incomplete_details
- model
- previous_response_id
- instructions
- input
- output
- error
- tools
- tool_choice
- temperature
- top_p
- presence_penalty
- frequency_penalty
- top_logprobs
- max_output_tokens
- max_tool_calls
- reasoning
- text
- user
- usage
- truncation
- parallel_tool_calls
- store
- background
- metadata
- service_tier
- safety_identifier
- prompt_cache_key
- prompt_cache_retention
- prompt_cache_options
type: object
description: Response retrieved successfully.
'404':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/APIError'
required:
- error
type: object
description: Response not found.
components:
schemas:
ConversationParam:
additionalProperties: false
properties:
id:
type: string
required:
- id
type: object
ResponseError:
additionalProperties: false
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
IncompleteDetails:
additionalProperties: false
properties:
reason:
type: string
required:
- reason
type: object
MemoryParam:
additionalProperties: false
properties:
entity_id:
type: string
required:
- entity_id
type: object
OpenAIPromptCacheOptions:
additionalProperties: false
properties:
mode:
enum:
- implicit
- explicit
type: string
ttl:
enum:
- 30m
type: string
type: object
Reasoning:
additionalProperties: false
properties:
effort:
description: >-
Constrains effort on reasoning for reasoning models. Reducing
reasoning effort can result in faster responses and fewer tokens
used on reasoning in a response.
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
type: string
summary:
description: The format of the reasoning summary returned by the model.
enum:
- concise
- detailed
- auto
- null
type:
- string
- 'null'
type: object
ResponseTelemetry:
additionalProperties: false
properties:
span_id:
type: string
trace_id:
type: string
required:
- trace_id
- span_id
type: object
PublicUsage:
additionalProperties: false
properties:
input_cost:
description: >-
Cost (USD) of input tokens. Present when billing was computed for
this response.
format: double
type: number
input_tokens:
format: int64
type: integer
input_tokens_details:
$ref: '#/components/schemas/InputTokensDetails'
output_cost:
description: >-
Cost (USD) of output tokens. Present when billing was computed for
this response.
format: double
type: number
output_tokens:
format: int64
type: integer
output_tokens_details:
$ref: '#/components/schemas/OutputTokensDetails'
server_tool_use:
$ref: '#/components/schemas/ServerToolUseDetails'
description: >-
Per-tool breakdown of server tool calls (provider-native and
orq-executed) made during this response.
total_cost:
description: >-
Total cost (USD) of the response. Present when billing was computed
for this response.
format: double
type: number
total_tokens:
format: int64
type: integer
web_search_requests:
format: int64
type: integer
required:
- input_tokens
- output_tokens
- total_tokens
- input_tokens_details
- output_tokens_details
type: object
APIError:
additionalProperties: false
properties:
code:
type:
- string
- 'null'
failures: {}
message:
type: string
param:
type:
- string
- 'null'
type:
type: string
required:
- message
- type
- param
- code
type: object
InputTokensDetails:
additionalProperties: false
properties:
cache_creation_1h_tokens:
format: int64
type: integer
cache_creation_5m_tokens:
format: int64
type: integer
cache_creation_tokens:
format: int64
type: integer
cache_write_tokens:
format: int64
type: integer
cached_tokens:
format: int64
type: integer
required:
- cached_tokens
- cache_write_tokens
- cache_creation_tokens
type: object
OutputTokensDetails:
additionalProperties: false
properties:
reasoning_tokens:
format: int64
type: integer
required:
- reasoning_tokens
type: object
ServerToolUseDetails:
additionalProperties: false
properties:
advisor_requests:
format: int64
type: integer
code_interpreter_sessions:
format: int64
type: integer
datetime_requests:
format: int64
type: integer
fusion_requests:
format: int64
type: integer
image_generation_calls:
format: int64
type: integer
search_models_requests:
format: int64
type: integer
shell_commands:
format: int64
type: integer
subagent_requests:
format: int64
type: integer
web_fetch_requests:
format: int64
type: integer
web_search_requests:
format: int64
type: integer
type: object
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.