> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve response

> Retrieves a previously created response by its ID.

> [!NOTE]
>
> **Guia relacionado**: guia da Responses API. Consulte o [guia da Responses API](/docs/pt-BR/ai-gateway/features/responses-api.md) para um passo a passo com exemplos.

Recupera uma resposta criada anteriormente pelo seu ID. A resposta precisa ter sido criada com `store: true` (o padrão).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://router.toqan.ai/eu/v3/router/responses/resp_01KP6GDNJY5B0TT0R35KS23PYV \
  -H "Authorization: Bearer $TOQAN_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: Toqan Router API
  version: '2.0'
  description: Toqan Router API documentation
servers:
  - url: https://router.toqan.ai/eu
    description: Frankfurt (Europe)
  - url: https://router.toqan.ai/br
    description: São Paulo (Brazil)
security:
  - ApiKey: []
tags:
  - description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
    name: API keys
  - 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: 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.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - name: Views
    description: Saved filters and columns for workspace observability pages.
  - description: List models available through the AI Router.
    name: Models
  - name: Alerts
    description: >-
      Alerts evaluate a telemetry 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: 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: 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 Toqan Router model catalog: every model Toqan Router 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: Monitors
    description: >-
      Monitors are custom observability dashboards for traces, runtime metrics,
      and logs. Each monitor holds widgets that chart one telemetry query. List
      the metrics, operations, and dimensions available to your workspace with
      `GET /v3/telemetry/capabilities`, or start from a preset with `GET
      /v2/monitors/presets`.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - 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: 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: Responses
  - name: Embeddings
  - description: Beta. Run typed classification questions against a classify model.
    name: Classify
  - description: Beta. Run classification decisions with the classify contract.
    name: Decisions
  - description: >-
      Run large offline workloads as JSONL batches and download
      OpenAI-compatible result files.
    name: Batches
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: >-
                      Always null. Retained for compatibility with older SDKs;
                      input content is not returned.
                    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<string, string>`).
                    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
                      - ultrafast
                      - 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:
                type: object
                additionalProperties: false
                properties:
                  error:
                    $ref: '#/components/schemas/APIError'
                required:
                  - error
          description: Response not found.
      security:
        - ApiKey: []
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
            - 12h
          type: string
      type: object
    Reasoning:
      additionalProperties: false
      properties:
        context:
          enum:
            - auto
            - current_turn
            - all_turns
          type: string
        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
            - instant
            - 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
            router-executed) made during this response.
        speed:
          description: Inference speed reported by Anthropic and used for billing.
          enum:
            - standard
            - fast
          type: string
        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
        cache_write_tokens_details:
          $ref: '#/components/schemas/CacheWriteTokensDetails'
        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
        tool_search_requests:
          format: int64
          type: integer
        web_fetch_requests:
          format: int64
          type: integer
        web_search_requests:
          format: int64
          type: integer
      type: object
    CacheWriteTokensDetails:
      additionalProperties: false
      properties:
        ttl_12h_tokens:
          format: int64
          type: integer
        ttl_30m_tokens:
          format: int64
          type: integer
      required:
        - ttl_30m_tokens
        - ttl_12h_tokens
      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.