Get Request by ID

Retrieve a specific request by its ID

GET /v1/request/{requestId}

Get Request by ID

cURL

curl --request GET \
  --url https://api.helicone.ai/v1/request/{requestId}

200

{
  "data": {
    "request_id": "<string>",
    "request_created_at": "<string>",
    "request_body": {},
    "request_path": "<string>",
    "request_user_id": {},
    "request_properties": {},
    "request_model": {},
    "response_id": {},
    "response_created_at": {},
    "response_body": {},
    "response_status": 123,
    "response_model": {},
    "model_override": {},
    "helicone_user": {},
    "provider": "<string>",
    "delay_ms": {},
    "time_to_first_token": {},
    "total_tokens": {},
    "prompt_tokens": {},
    "completion_tokens": {},
    "reasoning_tokens": {},
    "prompt_cache_write_tokens": {},
    "prompt_cache_read_tokens": {},
    "prompt_audio_tokens": {},
    "completion_audio_tokens": {},
    "cost": {},
    "costUSD": {},
    "prompt_id": {},
    "prompt_version": {},
    "feedback_created_at": {},
    "feedback_id": {},
    "feedback_rating": {},
    "signed_body_url": {},
    "llmSchema": {},
    "country_code": {},
    "asset_ids": {},
    "asset_urls": {},
    "scores": {},
    "properties": {},
    "assets": [
      "<string>"
    ],
    "target_url": "<string>",
    "model": "<string>",
    "cache_reference_id": {},
    "cache_enabled": true,
    "updated_at": "<string>",
    "request_referrer": {},
    "storage_location": "<string>"
  },
  "error": {}
}

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

Path Parameters

requestId · string · required

The unique identifier of the request to retrieve. This can be found in the Helicone-Id response header when making requests through Helicone, or in the request_id field when querying requests.

Example: req_abc123def456

Query Parameters

includeBody · boolean · default: "false"

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

• true - Returns full request/response bodies (may be large)
• false - Returns metadata only, with signed URLs for accessing bodies

Setting this to true may significantly increase response size for requests with large payloads.

Response

data · HeliconeRequest

The request object with full details.

Show HeliconeRequest object

request_id · string

Unique identifier for the request.

request_created_at · string

ISO 8601 timestamp of when the request was created.

Example: "2024-01-15T14:30:00.000Z"

request_body · object

The request payload sent to the LLM provider. Only included when includeBody=true.

request_path · string

API endpoint path that was called.

Example: "/v1/chat/completions"

request_user_id · string | null

User ID associated with the request (from Helicone-User-Id header).

request_properties · object | null

Custom properties attached to the request via Helicone-Property-* headers.

Example:

{
  "Environment": "production",
  "Conversation": "support_123",
  "App": "mobile"
}

request_model · string | null

Model name from the request.

Example: "gpt-4"

response_id · string | null

Unique identifier for the response.

response_created_at · string | null

ISO 8601 timestamp of when the response was created.

response_body · object

The response payload from the LLM provider. Only included when includeBody=true.

response_status · number

HTTP status code of the response.

Example: 200, 400, 500

response_model · string | null

Model name from the response (may differ from request_model).

model_override · string | null

Model override specified via Helicone-Model-Override header.

helicone_user · string | null

User identifier from Helicone-User-Id header.

provider · string

LLM provider name.

Examples: "OPENAI", "ANTHROPIC", "AZURE", "GOOGLE", "TOGETHER_AI"

delay_ms · number | null

Total latency in milliseconds from request to response completion.

time_to_first_token · number | null

Time to first token in milliseconds (for streaming requests).

total_tokens · number | null

Total tokens used (prompt + completion).

prompt_tokens · number | null

Number of tokens in the prompt/input.

completion_tokens · number | null

Number of tokens in the completion/output.

reasoning_tokens · number | null

Number of reasoning tokens (for reasoning models like o1).

prompt_cache_write_tokens · number | null

Number of tokens written to prompt cache.

prompt_cache_read_tokens · number | null

Number of tokens read from prompt cache.

prompt_audio_tokens · number | null

Number of audio tokens in the prompt (for multimodal models).

completion_audio_tokens · number | null

Number of audio tokens in the completion (for multimodal models).

cost · number | null

Cost of the request in USD.

costUSD · number | null

Alternative field for cost in USD.

prompt_id · string | null

Prompt ID from Helicone-Prompt-Id header.

prompt_version · string | null

Prompt version identifier.

feedback_created_at · string | null

Timestamp when feedback was added to this request.

feedback_id · string | null

Unique identifier for the feedback.

feedback_rating · boolean | null

Feedback rating (true for positive, false for negative).

signed_body_url · string | null

Presigned URL to download the full request/response body (when includeBody=false).

llmSchema · object | null

Normalized LLM schema containing structured request and response data.

country_code · string | null

Country code of the request origin.

asset_ids · string[] | null

Array of asset IDs associated with this request.

asset_urls · object | null

Map of asset IDs to their URLs.

scores · object | null

Evaluation scores attached to this request.

Example:

{
  "accuracy": 95,
  "relevance": 87,
  "helpfulness": 92
}

properties · object

Custom properties attached to the request.

assets · string[]

Array of asset identifiers.

target_url · string

The target URL that was proxied to.

model · string

The model used for this request.

cache_reference_id · string | null

Cache reference ID if this request was cached.

cache_enabled · boolean

Whether caching was enabled for this request.

updated_at · string

ISO 8601 timestamp of when the request was last updated.

request_referrer · string | null

Referrer information from the request.

storage_location · string

Storage location identifier for the request data.

error · string | null

Error message if the request failed.

Examples

Get Request Metadata Only

Retrieve request metadata without the full body:

cURL

curl --request GET \
  --url https://api.helicone.ai/v1/request/req_abc123def456 \
  --header 'Authorization: Bearer <HELICONE_API_KEY>'

TypeScript

const requestId = 'req_abc123def456';

const response = await fetch(
  `https://api.helicone.ai/v1/request/${requestId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`
    }
  }
);

const result = await response.json();
console.log(result.data);

Python

import os
import requests

request_id = "req_abc123def456"

response = requests.get(
    f"https://api.helicone.ai/v1/request/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['HELICONE_API_KEY']}"
    }
)

result = response.json()
print(result["data"])

Get Request with Full Body

Retrieve request with full request and response bodies:

cURL

curl --request GET \
  --url 'https://api.helicone.ai/v1/request/req_abc123def456?includeBody=true' \
  --header 'Authorization: Bearer <HELICONE_API_KEY>'

TypeScript

const requestId = 'req_abc123def456';

const response = await fetch(
  `https://api.helicone.ai/v1/request/${requestId}?includeBody=true`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`
    }
  }
);

const result = await response.json();
console.log(result.data.request_body);
console.log(result.data.response_body);

Python

import os
import requests

request_id = "req_abc123def456"

response = requests.get(
    f"https://api.helicone.ai/v1/request/{request_id}",
    params={"includeBody": True},
    headers={
        "Authorization": f"Bearer {os.environ['HELICONE_API_KEY']}"
    }
)

result = response.json()
print(result["data"]["request_body"])
print(result["data"]["response_body"])

Extract Request ID from Response Headers

When making a request through Helicone, you can extract the request ID from the response headers:

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://gateway.helicone.ai/v1',
  defaultHeaders: {
    'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`
  }
});

// Make a request and get the response with headers
const { data, response } = await client.chat.completions
  .create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  })
  .withResponse();

// Extract the request ID
const requestId = response.headers.get('helicone-id');
console.log('Request ID:', requestId);

// Now you can retrieve this request later
const requestDetails = await fetch(
  `https://api.helicone.ai/v1/request/${requestId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`
    }
  }
);

Python

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://gateway.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}"
    }
)

# Make a request
response = client.with_raw_response.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Extract the request ID
request_id = response.headers.get("helicone-id")
print(f"Request ID: {request_id}")

# Now you can retrieve this request later
import requests

request_details = requests.get(
    f"https://api.helicone.ai/v1/request/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['HELICONE_API_KEY']}"
    }
)

Use Cases

Debugging Failed Requests

Retrieve full details of a failed request to debug issues:

const debugRequest = async (requestId: string) => {
  const response = await fetch(
    `https://api.helicone.ai/v1/request/${requestId}?includeBody=true`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`
      }
    }
  );
  
  const result = await response.json();
  const request = result.data;
  
  if (request.response_status >= 400) {
    console.log('Failed request details:');
    console.log('Status:', request.response_status);
    console.log('Model:', request.model);
    console.log('Error:', request.response_body?.error);
    console.log('Request body:', request.request_body);
  }
};

Cost Analysis

Analyze costs and tokens for specific requests:

const analyzeRequest = async (requestId: string) => {
  const response = await fetch(
    `https://api.helicone.ai/v1/request/${requestId}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.HELICONE_API_KEY}`
      }
    }
  );
  
  const result = await response.json();
  const request = result.data;
  
  console.log('Cost Analysis:');
  console.log('Model:', request.model);
  console.log('Total cost:', `$${request.cost}`);
  console.log('Prompt tokens:', request.prompt_tokens);
  console.log('Completion tokens:', request.completion_tokens);
  console.log('Total tokens:', request.total_tokens);
  console.log('Latency:', `${request.delay_ms}ms`);
};

Related Endpoints

Query Requests

Query multiple requests with filters

Add Feedback

Add feedback to this request

Add Properties

Add custom properties to this request

Add Scores

Add evaluation scores to this request