Get Request

Retrieve a single request by ID

Overview

Retrieve detailed information about a specific request using its unique identifier. This endpoint returns comprehensive data about both the request and response, including metadata, token usage, costs, and custom properties.

Endpoint

method · string · required

GET

url · string · required

/v1/request/

Authentication

Requires API key authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

requestId · string · required

The unique identifier of the request to retrieve

Query Parameters

includeBody · boolean · default: "false"

Whether to include the full request and response bodies in the response.

• true - Includes complete request/response payloads
• false - Returns metadata only (faster, smaller response)

Response

Returns a single request object with detailed information.

data · object

The request object

Show Request Object Properties

request_id · string

Unique identifier for the request

request_created_at · string

Timestamp when the request was created (ISO 8601 format)

request_body · object

The complete request payload sent to the LLM provider (if includeBody=true)

request_path · string

API endpoint path (e.g., “/v1/chat/completions”)

request_user_id · string

User identifier associated with the request

request_properties · object

Custom properties attached to the request at creation time

request_model · string

Model specified in the original API request

response_id · string

Unique identifier for the response

response_created_at · string

Timestamp when the response was received (ISO 8601 format)

response_body · object

The complete response payload from the LLM provider (if includeBody=true)

response_status · number

HTTP status code of the response (e.g., 200, 400, 500)

response_model · string

Actual model used by the provider (may differ from requested model)

model_override · string

Model override applied via Helicone settings

provider · string

LLM provider name (e.g., “OPENAI”, “ANTHROPIC”, “AZURE”, “GOOGLE”)

model · string

Resolved model identifier

target_url · string

The actual URL the request was sent to

delay_ms · number

Total request latency in milliseconds (from request to response)

time_to_first_token · number

Time to first token in milliseconds (for streaming responses)

total_tokens · number

Total tokens used (prompt + completion)

prompt_tokens · number

Number of tokens in the prompt/input

completion_tokens · number

Number of tokens in the completion/output

prompt_cache_write_tokens · number

Tokens written to prompt cache (for providers that support caching)

prompt_cache_read_tokens · number

Tokens read from prompt cache

reasoning_tokens · number

Reasoning tokens used (for models like o1)

prompt_audio_tokens · number

Audio tokens in the prompt (for multimodal models)

completion_audio_tokens · number

Audio tokens in the completion (for multimodal models)

cost · number

Estimated cost of the request in USD

costUSD · number

Cost in USD (same as cost field)

prompt_id · string

ID of the prompt template used (if applicable)

prompt_version · string

Version of the prompt template used

feedback_id · string

ID of the feedback record (if feedback was provided)

feedback_rating · boolean

User feedback rating (true for positive, false for negative)

feedback_created_at · string

Timestamp when feedback was created

scores · object

Evaluation scores as key-value pairs (e.g., {"accuracy": 0.95})

properties · object

All custom properties associated with the request

asset_ids · array

Array of asset IDs associated with the request (e.g., images, files)

asset_urls · object

Map of asset IDs to their signed URLs

cache_enabled · boolean

Whether caching was enabled for this request

cache_reference_id · string

Reference ID for cached responses

country_code · string

Country code of the request origin (ISO 3166-1 alpha-2)

helicone_user · string

Helicone user identifier

updated_at · string

Last update timestamp for the request record

error · string

Error message if the request failed

Examples

Basic Request

Retrieve a request without body data:

curl -X GET "https://api.helicone.ai/v1/request/req_123abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request with Full Body

Retrieve a request including complete request and response bodies:

curl -X GET "https://api.helicone.ai/v1/request/req_123abc?includeBody=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using in Code

TypeScript

const response = await fetch(
  'https://api.helicone.ai/v1/request/req_123abc?includeBody=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const result = await response.json();

if (result.data) {
  console.log('Request Model:', result.data.model);
  console.log('Total Tokens:', result.data.total_tokens);
  console.log('Cost:', result.data.cost);
  console.log('Latency:', result.data.delay_ms, 'ms');
}

Response Example

{
  "data": {
    "request_id": "req_123abc",
    "request_created_at": "2024-01-15T10:30:00.000Z",
    "request_path": "/v1/chat/completions",
    "request_model": "gpt-4",
    "request_user_id": "user_456",
    "request_properties": {
      "environment": "production",
      "version": "1.2.3"
    },
    "request_body": {
      "model": "gpt-4",
      "messages": [
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ],
      "temperature": 0.7
    },
    "response_id": "res_789def",
    "response_created_at": "2024-01-15T10:30:02.341Z",
    "response_status": 200,
    "response_model": "gpt-4-0613",
    "response_body": {
      "id": "chatcmpl-123",
      "object": "chat.completion",
      "created": 1705317002,
      "model": "gpt-4-0613",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "The capital of France is Paris."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 8,
        "total_tokens": 23
      }
    },
    "provider": "OPENAI",
    "model": "gpt-4-0613",
    "target_url": "https://api.openai.com/v1/chat/completions",
    "delay_ms": 2341,
    "time_to_first_token": 234,
    "total_tokens": 23,
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "cost": 0.00069,
    "costUSD": 0.00069,
    "feedback_rating": true,
    "scores": {
      "accuracy": 0.95
    },
    "properties": {
      "environment": "production",
      "version": "1.2.3"
    },
    "cache_enabled": false,
    "updated_at": "2024-01-15T10:30:02.500Z"
  },
  "error": null
}

Error Responses

Request Not Found

{
  "data": null,
  "error": "Request not found"
}

Unauthorized

{
  "data": null,
  "error": "Unauthorized: Invalid API key"
}

Use Cases

• Debug specific requests: Investigate issues with particular API calls
• Audit trail: Review the complete history of a request and response
• Cost analysis: Check token usage and costs for specific requests
• Performance monitoring: Analyze latency and time-to-first-token metrics
• Quality assurance: Review requests with feedback or evaluation scores
• Compliance: Export specific requests for compliance or auditing purposes

Notes

• The includeBody parameter significantly increases response size but is necessary for debugging
• Request bodies may contain sensitive data - ensure proper access controls
• Asset URLs (if present) are pre-signed and time-limited
• The cost field is calculated based on token usage and current provider pricing
• Some fields may be null depending on the request type and provider